feat: add user management endpoints for creating and retrieving users#21
feat: add user management endpoints for creating and retrieving users#21No-99-Tongji wants to merge 5 commits intoapolloconfig:mainfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds OpenAPI definitions for user management: introduces Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
apollo-openapi.yaml (3)
3604-3612: Add a globalUser Managementtag definition.The new endpoints reference
User Management, but the top-leveltagslist doesn’t define it. Adding it keeps the docs organized and consistent.🧩 Suggested tag entry (add near other tags)
tags: - name: App Management description: 应用管理相关接口，包括应用的创建、查询、更新、删除等操作 + - name: User Management + description: 用户管理相关接口，包括用户的创建、查询、获取等操作🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3604 - 3612, Add a top-level tag definition for "User Management" in the OpenAPI spec so endpoints that reference it (e.g., operationId createUser under /openapi/v1/users) have a corresponding entry; update the global tags array to include an object with name: "User Management" and a brief description (like "Operations related to user accounts") so the tag is defined and appears in generated docs.
4468-4472: Mark password aswriteOnlyto prevent it from showing up in response models.This improves security posture for generated clients and avoids accidental exposure in tooling.
🔐 Suggested fix
password: type: string description: 用户密码，创建时必填，需满足密码强度要求 format: password + writeOnly: true example: "P@ssw0rd123"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 4468 - 4472, The "password" property in the OpenAPI schema is currently listed with format: password and example but is not marked writeOnly; update the schema for the "password" field (the property with format: password and example: "P@ssw0rd123") to include writeOnly: true so it is accepted on input but omitted from response models and generated clients.
3639-3656: Keep error response schemas consistent with the existingtype: object+allOfpattern.Most endpoints wrap
ExceptionResponseintype: object+allOfto keep generator output stable. These new responses use a direct$ref, which can diverge from the established pattern.🔧 Example adjustment (apply similarly to other new error responses)
- '400': - description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） - content: - application/json: - schema: - $ref: '#/components/schemas/ExceptionResponse' + '400': + description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/ExceptionResponse'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3639 - 3656, The new error responses ('400', '401', '403') use a direct $ref to ExceptionResponse which breaks the established generator-stable pattern; update each response's content schema to use the existing "type: object" + "allOf" wrapper instead of a direct $ref (e.g., replace schema: $ref: '#/components/schemas/ExceptionResponse' with schema: type: object and allOf: - $ref: '#/components/schemas/ExceptionResponse'), and apply the same change to any other newly added error responses to match the ExceptionResponse wrapping pattern.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apollo-openapi.yaml`:
- Around line 3759-3764: Replace the HTTP response entry keyed '400' for the
"用户不存在" case with a '404' response to reflect a not-found condition and maintain
consistency with other endpoints; update the response key from '400' to '404'
and keep the description "用户不存在" and the schema reference to ExceptionResponse
(or swap to a NotFound-specific schema if your spec uses one) so clients receive
the correct status code for user-not-found errors.
---
Nitpick comments:
In `@apollo-openapi.yaml`:
- Around line 3604-3612: Add a top-level tag definition for "User Management" in
the OpenAPI spec so endpoints that reference it (e.g., operationId createUser
under /openapi/v1/users) have a corresponding entry; update the global tags
array to include an object with name: "User Management" and a brief description
(like "Operations related to user accounts") so the tag is defined and appears
in generated docs.
- Around line 4468-4472: The "password" property in the OpenAPI schema is
currently listed with format: password and example but is not marked writeOnly;
update the schema for the "password" field (the property with format: password
and example: "P@ssw0rd123") to include writeOnly: true so it is accepted on
input but omitted from response models and generated clients.
- Around line 3639-3656: The new error responses ('400', '401', '403') use a
direct $ref to ExceptionResponse which breaks the established generator-stable
pattern; update each response's content schema to use the existing "type:
object" + "allOf" wrapper instead of a direct $ref (e.g., replace schema: $ref:
'#/components/schemas/ExceptionResponse' with schema: type: object and allOf: -
$ref: '#/components/schemas/ExceptionResponse'), and apply the same change to
any other newly added error responses to match the ExceptionResponse wrapping
pattern.
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
apollo-openapi.yaml (1)
3810-3815:⚠️ Potential issue | 🟠 Major
GET /openapi/v1/users/{userId}— 400 used for "user not found" should be 404."用户不存在" is a resource-not-found condition; HTTP 400 implies a malformed request. All other "not found" cases in this spec use 404 (
ExceptionResponse). Returning 400 here misleads clients and breaks consistent error handling.✅ Proposed fix
- '400': - description: 用户不存在 + '404': + description: 用户不存在 content: application/json: schema: $ref: '#/components/schemas/ExceptionResponse'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3810 - 3815, The response for GET /openapi/v1/users/{userId} is incorrectly using HTTP 400 for "用户不存在"; update the response status key from '400' to '404' so the path's "用户不存在" response aligns with other not-found cases and continues to reference the same ExceptionResponse schema (the block currently under '400' should be moved/renamed to '404'); ensure the schema/$ref and description remain unchanged and that any tests or examples expecting 400 are updated to 404.
🧹 Nitpick comments (3)
apollo-openapi.yaml (3)
3663-3665: Redundant per-operationsecuritydeclarations.
security: - ApiKeyAuth: []is identical to the global security requirement already declared at lines 22–23. Repeating it on every new operation adds noise without changing behavior.♻️ Proposed cleanup (apply to all three new operations)
- security: - - ApiKeyAuth: [] requestBody:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3663 - 3665, Remove the redundant per-operation security declarations by deleting the repeated "security: - ApiKeyAuth: []" blocks from the three new operations; the global ApiKeyAuth security requirement already applies, so keep the global security config and remove the per-operation "security" entries (look for the literal "security: - ApiKeyAuth: []" in the new operation definitions).
5979-6000:UserInfois a near-duplicate of the existingOpenUserInfoDTOschema.
OpenUserInfoDTO(lines 5740–5754) already defines identical fields:userId,name,enabled(alltype: integer/string). The only differences are thatUserInfoadds descriptions, examples, and anenum: [0, 1]constraint onenabled.Having two schemas for the same concept causes drift (e.g.,
OpenEnvNamespaceRoleUserDTOet al. referenceOpenUserInfoDTOwhile the new user endpoints useUserInfo). Consider enrichingOpenUserInfoDTOwith the new descriptions andenumconstraint instead, and pointing the new endpoints at it.♻️ Proposed consolidation
Enrich the existing schema:
OpenUserInfoDTO: type: object + description: 用户信息 properties: userId: type: string - description: '' + description: 用户ID（即用户名） + example: "apollo" name: type: string - description: '' + description: 用户显示名称 + example: "Apollo Admin" email: type: string - description: '' + description: 用户邮箱 + format: email + example: "apollo@example.com" enabled: type: integer - description: '' + description: 用户状态：1-启用，0-停用 + enum: [0, 1] + example: 1Then replace all
$ref: '#/components/schemas/UserInfo'in the new endpoints with$ref: '#/components/schemas/OpenUserInfoDTO'and remove theUserInfoschema.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 5979 - 6000, UserInfo duplicates OpenUserInfoDTO; consolidate by enriching OpenUserInfoDTO with the missing descriptions, examples and the enabled enum ([0,1]) (update the schema object named OpenUserInfoDTO to include description/example for userId, name, email and the enum constraint on enabled), then update all new endpoints that currently $ref '#/components/schemas/UserInfo' to instead $ref '#/components/schemas/OpenUserInfoDTO' (search for references like those in the new user endpoints), and finally remove the duplicate UserInfo schema; ensure related DTO references such as OpenEnvNamespaceRoleUserDTO remain pointing at OpenUserInfoDTO.
5910-5944:MultiResponseEntityandRichResponseEntityare defined but never referenced by any endpoint.No path in the spec uses
$ref: '#/components/schemas/MultiResponseEntity'or$ref: '#/components/schemas/RichResponseEntity'. Dead schemas add confusion and inflate generated client SDKs.Either remove them until an endpoint actually needs them, or add a comment explaining their intended future use.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 5910 - 5944, The schemas MultiResponseEntity and RichResponseEntity are defined but unused; either delete their definitions from components.schemas (remove the entries for MultiResponseEntity and RichResponseEntity) or keep them but update their descriptions to include an explicit note about intended future use (e.g., "Reserved for endpoints that return multiple RichResponseEntity items") so they are not considered dead; ensure any change references the exact schema names MultiResponseEntity and RichResponseEntity so tooling and reviewers can locate the edits.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apollo-openapi.yaml`:
- Around line 3677-3707: The OpenAPI operation for POST /openapi/v1/users is
missing a 409 Conflict response for duplicate usernames; update the responses
section for that operation to add a '409' response entry (mirroring the existing
error response shape) that uses the same ExceptionResponse schema and a
description like "用户名已存在（重复）" so clients can distinguish duplicate-user errors
from generic 400 validation errors. Ensure the new '409' entry is added
alongside '400','401','403' and references
'#/components/schemas/ExceptionResponse' with appropriate content type
application/json.
- Around line 3655-3662: The OpenAPI spec uses the tag "User Management" in
operations (e.g., operationId createUser on path /openapi/v1/users POST) but
that tag is not declared in the top-level tags array; add a top-level tag object
with name "User Management" (and an optional description) to the root tags
section so tooling can recognize and render the referenced tag for all
operations that list "- User Management".
- Around line 3648-3654: The response references a missing schema
'#/components/schemas/SuccessEmptyResponse' and redundantly wraps a single $ref
inside allOf; either remove the entire content block for this 200 response (if
it should be body-less) or add a proper schema definition under
components.schemas named SuccessEmptyResponse and reference it directly (drop
the surrounding type: object + allOf). Locate the OpenAPI response that contains
the content/application/json/schema with allOf -> $ref and apply one of the two
fixes so codegen/validation no longer fails.
---
Duplicate comments:
In `@apollo-openapi.yaml`:
- Around line 3810-3815: The response for GET /openapi/v1/users/{userId} is
incorrectly using HTTP 400 for "用户不存在"; update the response status key from
'400' to '404' so the path's "用户不存在" response aligns with other not-found cases
and continues to reference the same ExceptionResponse schema (the block
currently under '400' should be moved/renamed to '404'); ensure the schema/$ref
and description remain unchanged and that any tests or examples expecting 400
are updated to 404.
---
Nitpick comments:
In `@apollo-openapi.yaml`:
- Around line 3663-3665: Remove the redundant per-operation security
declarations by deleting the repeated "security: - ApiKeyAuth: []" blocks from
the three new operations; the global ApiKeyAuth security requirement already
applies, so keep the global security config and remove the per-operation
"security" entries (look for the literal "security: - ApiKeyAuth: []" in the new
operation definitions).
- Around line 5979-6000: UserInfo duplicates OpenUserInfoDTO; consolidate by
enriching OpenUserInfoDTO with the missing descriptions, examples and the
enabled enum ([0,1]) (update the schema object named OpenUserInfoDTO to include
description/example for userId, name, email and the enum constraint on enabled),
then update all new endpoints that currently $ref
'#/components/schemas/UserInfo' to instead $ref
'#/components/schemas/OpenUserInfoDTO' (search for references like those in the
new user endpoints), and finally remove the duplicate UserInfo schema; ensure
related DTO references such as OpenEnvNamespaceRoleUserDTO remain pointing at
OpenUserInfoDTO.
- Around line 5910-5944: The schemas MultiResponseEntity and RichResponseEntity
are defined but unused; either delete their definitions from components.schemas
(remove the entries for MultiResponseEntity and RichResponseEntity) or keep them
but update their descriptions to include an explicit note about intended future
use (e.g., "Reserved for endpoints that return multiple RichResponseEntity
items") so they are not considered dead; ensure any change references the exact
schema names MultiResponseEntity and RichResponseEntity so tooling and reviewers
can locate the edits.
|
主仓库的PR链接：apolloconfig/apollo#5554 |
…additional error handling
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apollo-openapi.yaml`:
- Around line 5954-5958: Replace the current fixed object schema for
RichResponseEntity.message with a union using oneOf that allows either a string
or an object (e.g., oneOf: - type: string; - type: object / or a $ref to the
existing object schema), update the description to reflect "string or object"
and adjust the example(s) to match the oneOf (provide an example for the string
case and/or an exampleObject entry for the object case) so linters and code
generators see a proper union type; locate the message property under the
RichResponseEntity schema to make these edits.
| message: | ||
| type: object | ||
| description: Response message (can be string or object) | ||
| example: "OK" | ||
| body: |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Examine the apollo-openapi.yaml file around lines 5954-5958
if [ -f "apollo-openapi.yaml" ]; then
echo "=== Lines 5950-5970 of apollo-openapi.yaml ==="
sed -n '5950,5970p' apollo-openapi.yaml
else
echo "File not found at root, searching for it..."
find . -name "apollo-openapi.yaml" -type f
fiRepository: apolloconfig/apollo-openapi
Length of output: 621
🌐 Web query:
OpenAPI 3.0 specification example validation must conform to schema type
💡 Result:
In OpenAPI 3.0.x, example values are not required (“MUST”) to conform to the schema type, but they are expected/encouraged to.
- Media Type Object (
content.*.example/content.*.examples): the spec says each example “SHOULD match” the media type and the specified schema (if present)—so it’s a recommendation, not a hard requirement. [1] - Example Object (
components.examples.*.value): the spec says the example value is expected to be compatible with the associated schema type, and tools MAY choose to validate and reject incompatible examples. [2]
So: spec-wise, non-conforming examples don’t make the OAS 3.0 document invalid, but many linters/validators can (optionally) enforce example-vs-schema compatibility. [2]
Sources:
[1] OpenAPI Spec 3.0.3 – Media Type Object (example/examples “SHOULD match” schema) (spec.openapis.org)
[2] OpenAPI Spec 3.0.1 – Example Object (compatibility expected; tooling MAY validate) (spec.openapis.org)
Citations:
- 1: https://spec.openapis.org/oas/v3.0.3?utm_source=openai
- 2: https://spec.openapis.org/oas/v3.0.1.html?utm_source=openai
🌐 Web query:
OpenAPI 3.0 oneOf vs anyOf for union types string or object best practices
💡 Result:
oneOf vs anyOf (OpenAPI 3.0) — what to use for “string or object”
- Prefer
oneOffor union types (either this schema or that schema), because it means the instance must validate against exactly one option (exclusive OR). This is the clearest intent for “string-or-object”. [1][2] - Use
anyOfsparingly for structural unions, because it means the instance may validate against one or more options, which can create ambiguity and inconsistent tooling/validator behavior when schemas overlap. Many guidance sources recommend avoidinganyOffor “either/or” payload shapes. [1][2]
Practical rule for string | object
- If the alternatives are different JSON types (e.g.,
type: stringvstype: object), thenoneOfandanyOfbehave the same in practice (the instance can’t be both a string and an object). Still,oneOfis the better signal to humans/tools that it’s a true union. [3][2]
Best-practice schema pattern (OpenAPI 3.0)
MyField:
oneOf:
- type: string
description: ID reference form
- type: object
additionalProperties: false
required: [id]
properties:
id:
type: string
description: Expanded object formTips to keep it robust:
- Make the object variant strict and distinguishable (e.g.,
required,additionalProperties: false) to avoid accidental overlap in more complex unions. [1] - If your union is object-vs-object, add a discriminating property (often a
"type"with an enum) and consider OpenAPI’sdiscriminatorto improve tooling/SDK generation. (Discriminator is defined for use withoneOf/anyOf/allOf.) [4]
Why not type: [string, object] in OAS 3.0?
OpenAPI 3.0’s Schema Object does not support multiple types via a type array, so unions should be modeled with oneOf/anyOf. [5]
Sources: Redocly guidance on preferring oneOf and avoiding anyOf for structural alternatives [1]; Swagger docs on oneOf/anyOf semantics [2]; StackOverflow note that anyOf can often be replaced by oneOf when types differ [3]; OpenAPI spec on discriminator usage with composition keywords [4]; OAS 3.0.1 spec note that multiple types via an array are not supported [5].
Align RichResponseEntity.message schema with its documented payload type.
The message property is declared as type: object, but its example is a string ("OK"), and the description indicates it can be either string or object. While OpenAPI 3.0 does not strictly require examples to conform to the declared schema, this mismatch will likely trigger validation warnings in linters and generate inconsistent client code. Per OpenAPI best practices, use oneOf to explicitly model the union type.
🔧 Proposed fix
RichResponseEntity:
type: object
description: "Reserved for future use as a wrapper for a single response entity with code, message, and body."
properties:
code:
type: integer
description: HTTP status code
example: 200
message:
- type: object
+ oneOf:
+ - type: string
+ - type: object
description: Response message (can be string or object)
example: "OK"
body:
type: object
description: Response payload (generic type T)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apollo-openapi.yaml` around lines 5954 - 5958, Replace the current fixed
object schema for RichResponseEntity.message with a union using oneOf that
allows either a string or an object (e.g., oneOf: - type: string; - type: object
/ or a $ref to the existing object schema), update the description to reflect
"string or object" and adjust the example(s) to match the oneOf (provide an
example for the string case and/or an exampleObject entry for the object case)
so linters and code generators see a proper union type; locate the message
property under the RichResponseEntity schema to make these edits.
apollo-openapi.yaml
Outdated
| version: 1.0.0 | ||
| security: | ||
| - ApiKeyAuth: [] | ||
| - ApiKeyAuth: [ ] |
There was a problem hiding this comment.
I think we can split the formatter and content
|
I think we can remove the format(or open a new PR), and discuss the API details, once this API detail is approved, we can release a new version. @nobodyiam @No-99-Tongji |
There was a problem hiding this comment.
🧹 Nitpick comments (2)
apollo-openapi.yaml (2)
3687-3715: Consider using direct$reffor error response schemas.The error responses wrap the schema reference in
type: object+allOf, which is redundant and inconsistent with other endpoints in this spec that use direct references. This pattern may cause code generators to produce different types for identical error responses.♻️ Proposed simplification
'400': description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） content: application/json: schema: - type: object - allOf: - - $ref: '#/components/schemas/ExceptionResponse' + $ref: '#/components/schemas/ExceptionResponse' '401': description: 未授权访问 content: application/json: schema: - type: object - allOf: - - $ref: '#/components/schemas/ExceptionResponse' + $ref: '#/components/schemas/ExceptionResponse'Apply the same simplification to all error responses in the new user endpoints (400, 401, 403, 409, 404).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3687 - 3715, The error responses for the new-user endpoints currently wrap the schema as "type: object" plus "allOf: - $ref: '#/components/schemas/ExceptionResponse'"; replace those with a direct schema $ref to the shared ExceptionResponse for each error response (e.g., replace the schema blocks under response codes 400, 401, 403, 404, 409 with "schema: $ref: '#/components/schemas/ExceptionResponse'") so they match other endpoints and avoid generator inconsistencies; update the response blocks for '400', '401', '403', '404', and '409' in the new user endpoints accordingly.
3738-3754: Pagination style differs from other endpoints.This endpoint uses
offset/limitparameters while most other paginated endpoints in the spec usepage/size(e.g.,/openapi/v1/apps/by-self,/openapi/v1/envs/{env}/apps/{appId}/clusters/{clusterName}/namespaces/{namespaceName}/items). Both patterns are valid, but the inconsistency may confuse API consumers.Consider aligning with the existing pagination convention for a more uniform API experience, or document this difference explicitly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3738 - 3754, This endpoint currently uses offset/limit which is inconsistent with the rest of the API; change the two query parameters to page (integer, default 1, minimum 1) and size (integer, default 10, minimum 1, maximum 100) and update their descriptions to match the convention used by endpoints like /openapi/v1/apps/by-self; also ensure any server-side handlers or docs that reference offset/limit are updated to use page/size (or convert page/size to offset internally) so behavior remains identical.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@apollo-openapi.yaml`:
- Around line 3687-3715: The error responses for the new-user endpoints
currently wrap the schema as "type: object" plus "allOf: - $ref:
'#/components/schemas/ExceptionResponse'"; replace those with a direct schema
$ref to the shared ExceptionResponse for each error response (e.g., replace the
schema blocks under response codes 400, 401, 403, 404, 409 with "schema: $ref:
'#/components/schemas/ExceptionResponse'") so they match other endpoints and
avoid generator inconsistencies; update the response blocks for '400', '401',
'403', '404', and '409' in the new user endpoints accordingly.
- Around line 3738-3754: This endpoint currently uses offset/limit which is
inconsistent with the rest of the API; change the two query parameters to page
(integer, default 1, minimum 1) and size (integer, default 10, minimum 1,
maximum 100) and update their descriptions to match the convention used by
endpoints like /openapi/v1/apps/by-self; also ensure any server-side handlers or
docs that reference offset/limit are updated to use page/size (or convert
page/size to offset internally) so behavior remains identical.
This format has now been removed. |
There was a problem hiding this comment.
🧹 Nitpick comments (2)
apollo-openapi.yaml (2)
49-50: Consider using consistent language for tag descriptions.Other tag descriptions in this file use Chinese (e.g., "应用管理相关接口，包括应用的创建、查询、更新、删除等操作"), but this new tag uses English. For consistency, consider updating to Chinese like the others:
💡 Suggested change
- name: User Management - description: Operations related to user accounts + description: 用户管理相关接口，包括用户的创建、查询等操作🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 49 - 50, The new OpenAPI tag "User Management" uses an English description while other tags use Chinese; update the tag's description to Chinese to match existing language style (e.g., replace the description for the tag named "User Management" with a Chinese phrase like "用户管理相关接口，包括用户的创建、查询、更新、删除等操作") so descriptions are consistent across tags.
3687-3715: Redundanttype: object+allOfwrapper for single schema reference.The error response schemas use an unnecessary wrapper pattern. When referencing a single schema, a direct
$refis sufficient:# Current (redundant) schema: type: object allOf: - $ref: '#/components/schemas/ExceptionResponse' # Simpler schema: $ref: '#/components/schemas/ExceptionResponse'This pattern appears in all four error responses (400, 401, 403, 409) for this endpoint and the other new user endpoints. Consider simplifying for consistency with other endpoints in this spec (e.g., lines 77-79, 134-137).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apollo-openapi.yaml` around lines 3687 - 3715, The response schemas for the error responses (responses '400', '401', '403', '409') are wrapped with an unnecessary "type: object" plus "allOf" containing a single $ref; replace each of those schema blocks with a direct reference to the ExceptionResponse schema (i.e., remove the "type: object" and "allOf" wrapper and use "schema: $ref: '#/components/schemas/ExceptionResponse'") so the endpoint responses match the simpler pattern used elsewhere; look for the schema blocks under the error response keys in the apollo-openapi.yaml for those status codes to update.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@apollo-openapi.yaml`:
- Around line 49-50: The new OpenAPI tag "User Management" uses an English
description while other tags use Chinese; update the tag's description to
Chinese to match existing language style (e.g., replace the description for the
tag named "User Management" with a Chinese phrase like
"用户管理相关接口，包括用户的创建、查询、更新、删除等操作") so descriptions are consistent across tags.
- Around line 3687-3715: The response schemas for the error responses (responses
'400', '401', '403', '409') are wrapped with an unnecessary "type: object" plus
"allOf" containing a single $ref; replace each of those schema blocks with a
direct reference to the ExceptionResponse schema (i.e., remove the "type:
object" and "allOf" wrapper and use "schema: $ref:
'#/components/schemas/ExceptionResponse'") so the endpoint responses match the
simpler pattern used elsewhere; look for the schema blocks under the error
response keys in the apollo-openapi.yaml for those status codes to update.
2 participants
Apollo主仓库的PR：提供一个创建用户的OpenAPI #5554需要的对apollo-openapi.yaml的修改：
在paths中添加了users的相关接口
在scemas中添加了OpenUserDTO和UserInfo的定义
Summary by CodeRabbit
New Features
Documentation
Style