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 2 commits intoapolloconfig:mainfrom
Conversation
📝 WalkthroughWalkthroughAdds OpenAPI specification entries for user management: create user, list/search users, fetch user by ID, plus four new component schemas for request/response wrappers and user representations. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 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)
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.
| '400': | ||
| description: 用户不存在 | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ExceptionResponse' |
There was a problem hiding this comment.
Use 404 for “user not found” instead of 400.
“用户不存在” is a not‑found condition and other endpoints use 404; returning 400 misleads clients and breaks consistent error handling.
✅ Suggested fix
- '400':
- description: 用户不存在
+ '404':
+ description: 用户不存在
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| '400': | |
| description: 用户不存在 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '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 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.
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.
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| allOf: | ||
| - $ref: '#/components/schemas/SuccessEmptyResponse' | ||
| headers: {} |
There was a problem hiding this comment.
Broken $ref — SuccessEmptyResponse schema is not defined.
#/components/schemas/SuccessEmptyResponse is referenced here but does not exist anywhere in components/schemas. This will fail OpenAPI validation and break all code generators.
Additionally, wrapping a single $ref inside allOf with an explicit type: object is redundant.
🛠️ Proposed fix
Option A — drop the content block entirely (the 200 response for an update is typically body-less):
'200':
description: '灰度规则更新成功'
- content:
- application/json:
- schema:
- type: object
- allOf:
- - $ref: '#/components/schemas/SuccessEmptyResponse'
headers: {}Option B — define and reference the missing schema (if a response body is actually needed):
# Under components/schemas:
+ SuccessEmptyResponse:
+ type: object
+ description: Empty success response body🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apollo-openapi.yaml` around lines 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.
| /openapi/v1/users: | ||
| post: | ||
| summary: 创建用户 | ||
| operationId: createUser | ||
| deprecated: false | ||
| description: POST /openapi/v1/users | ||
| tags: | ||
| - User Management |
There was a problem hiding this comment.
"User Management" tag is used but not declared in the top-level tags section.
All three new operations reference - User Management, which is absent from the tags list at lines 24–48. Most OpenAPI tooling (renderers, linters, validators) will either warn or produce broken navigation.
🛠️ Proposed fix — add tag declaration
- name: Permission Management
description: 权限管理相关接口，包括权限查询等功能
+ - name: User Management
+ description: 用户管理相关接口，包括用户的创建、查询等操作
paths:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apollo-openapi.yaml` around lines 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".
| responses: | ||
| '200': | ||
| description: 成功创建用户，返回创建的用户信息 | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/UserInfo' | ||
| example: | ||
| userId: "new-user" | ||
| name: "New User" | ||
| email: "new-user@example.com" | ||
| enabled: 1 | ||
| headers: {} | ||
| '400': | ||
| description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ExceptionResponse' | ||
| '401': | ||
| description: 未授权访问 | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ExceptionResponse' | ||
| '403': | ||
| description: 权限不足或当前用户服务不支持创建用户 | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ExceptionResponse' |
There was a problem hiding this comment.
POST /openapi/v1/users is missing a 409 Conflict response for duplicate usernames.
When a caller attempts to create a user whose username already exists, the server will reject the request. Without a 409 response code, clients have no contract to distinguish "duplicate user" from a generic 400 validation error, making error handling ambiguous.
🛠️ Proposed fix
'403':
description: 权限不足或当前用户服务不支持创建用户
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionResponse'
+ '409':
+ description: 用户名已存在
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ExceptionResponse'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| responses: | |
| '200': | |
| description: 成功创建用户，返回创建的用户信息 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| example: | |
| userId: "new-user" | |
| name: "New User" | |
| email: "new-user@example.com" | |
| enabled: 1 | |
| headers: {} | |
| '400': | |
| description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '401': | |
| description: 未授权访问 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '403': | |
| description: 权限不足或当前用户服务不支持创建用户 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| responses: | |
| '200': | |
| description: 成功创建用户，返回创建的用户信息 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| example: | |
| userId: "new-user" | |
| name: "New User" | |
| email: "new-user@example.com" | |
| enabled: 1 | |
| headers: {} | |
| '400': | |
| description: 请求参数错误（用户名/密码/邮箱为空，或密码强度不足） | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '401': | |
| description: 未授权访问 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '403': | |
| description: 权限不足或当前用户服务不支持创建用户 | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ExceptionResponse' | |
| '409': | |
| 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 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.
|
主仓库的PR链接：apolloconfig/apollo#5554 |
1 participant
Apollo主仓库的PR：提供一个创建用户的OpenAPI #5554需要的对apollo-openapi.yaml的修改：
在paths中添加了users的相关接口
在scemas中添加了OpenUserDTO和UserInfo的定义
Summary by CodeRabbit