From 327c52c975ac1bd0d19620a710cf0e98cc055709 Mon Sep 17 00:00:00 2001
From: Aofei Sheng <aofei@aofeisheng.com>
Date: Tue, 10 Feb 2026 17:58:51 +0800
Subject: [PATCH] docs(api-spec): add `displayName` field to project and user
 endpoints

Add `displayName` to the `Project` schema and related endpoints:
- Add optional `displayName` to `POST /project` request body, which
  defaults to `name` if not provided
- Add optional `displayName` to `PUT /project/{owner}/{name}` request
  body
- Update `keyword` parameter in `GET /projects/list` to search by
  display name or name, and decouple its schema from `Project.name`

Add `displayName` to the `PUT /user` endpoint for updating user profile
information, and make the request body require at least one of
`displayName` or `description` instead of always requiring `description`.

Signed-off-by: Aofei Sheng <aofei@aofeisheng.com>
---
 docs/openapi.yaml | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 42fa4ac8a..a72135e9a 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -107,11 +107,16 @@ paths:
           application/json:
             schema:
               type: object
-              required:
-                - description
               properties:
+                displayName:
+                  $ref: "#/components/schemas/User/properties/displayName"
                 description:
                   $ref: "#/components/schemas/User/properties/description"
+              anyOf:
+                - required:
+                    - displayName
+                - required:
+                    - description
       responses:
         "200":
           description: Successfully updated the authenticated user.
@@ -198,6 +203,9 @@ paths:
                     - $ref: "#/components/schemas/ProjectReleaseFullName"
                 name:
                   $ref: "#/components/schemas/Project/properties/name"
+                displayName:
+                  description: Defaults to `name` if not provided.
+                  $ref: "#/components/schemas/Project/properties/displayName"
                 files:
                   description: |
                     File paths and their corresponding universal URLs associated with the project.
@@ -267,10 +275,12 @@ paths:
               - $ref: "#/components/schemas/ProjectFullName"
               - $ref: "#/components/schemas/ProjectReleaseFullName"
         - name: keyword
-          description: Filter projects by name pattern.
+          description: Filter projects by display name or name pattern.
           in: query
           schema:
-            $ref: "#/components/schemas/Project/properties/name"
+            type: string
+            examples:
+              - Niu Xiao Qi
         - name: visibility
           description: Filter projects by visibility.
           in: query
@@ -400,6 +410,8 @@ paths:
                   $ref: "#/components/schemas/Project/properties/files"
                 visibility:
                   $ref: "#/components/schemas/Project/properties/visibility"
+                displayName:
+                  $ref: "#/components/schemas/Project/properties/displayName"
                 description:
                   $ref: "#/components/schemas/Project/properties/description"
                 instructions:
@@ -2550,6 +2562,11 @@ components:
           type: string
           examples:
             - NiuXiaoQi
+        displayName:
+          description: Display name of the project.
+          type: string
+          examples:
+            - Niu Xiao Qi
         version:
           description: Version number of the project.
           type: integer