From 2c318664305fd2723586ad939e64f958d9d447ff Mon Sep 17 00:00:00 2001 From: Rigel Kent Date: Sat, 27 Jun 2020 11:43:43 +0200 Subject: [PATCH] update openapi spec with links and callback for search --- server/controllers/api/users/index.ts | 2 +- support/doc/api/openapi.yaml | 112 +++++++++++++++++++++----- 2 files changed, 94 insertions(+), 20 deletions(-) diff --git a/server/controllers/api/users/index.ts b/server/controllers/api/users/index.ts index c8e9eaeaa..732a6faa3 100644 --- a/server/controllers/api/users/index.ts +++ b/server/controllers/api/users/index.ts @@ -205,7 +205,7 @@ async function createUser (req: express.Request, res: express.Response) { Hooks.runAction('action:api.user.created', { body, user, account, videoChannel }) - return res.json({ + return res.status(201).json({ user: { id: user.id, account: { diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 6c1ffee4f..3b06a2568 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -484,12 +484,30 @@ paths: tags: - Users responses: - '200': - description: successful operation + '201': + description: user created content: application/json: schema: $ref: '#/components/schemas/AddUserResponse' + links: + # GET /users/{id} + GetUserId: + operationId: getUserId + parameters: + id: '$response.body#/user/id' + # PUT /users/{id} + PutUserId: + operationId: putUserId + parameters: + id: '$response.body#/user/id' + # DELETE /users/{id} + DelUserId: + operationId: delUserId + parameters: + id: '$response.body#/user/id' + '403': + description: insufficient authority to create an admin or moderator requestBody: content: application/json: @@ -517,6 +535,8 @@ paths: items: $ref: '#/components/schemas/User' '/users/{id}': + parameters: + - $ref: '#/components/parameters/id' delete: summary: Delete a user security: @@ -524,8 +544,7 @@ paths: - admin tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: delUserId responses: '204': description: successful operation @@ -535,8 +554,7 @@ paths: - OAuth2: [] tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: getUserId responses: '200': description: successful operation @@ -550,8 +568,7 @@ paths: - OAuth2: [] tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: putUserId responses: '204': description: successful operation @@ -701,12 +718,28 @@ paths: '200': description: successful operation post: + tags: + - My Subscriptions summary: Add subscription to my user security: - OAuth2: - user - tags: - - My Subscriptions + requestBody: + content: + application/json: + schema: + type: object + properties: + uri: + type: string + format: uri + description: uri of the video channels to subscribe to + required: + - uri + examples: + default: + value: + uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr responses: '200': description: successful operation @@ -816,7 +849,7 @@ paths: - My Notifications requestBody: content: - multipart/form-data: + application/json: schema: type: object properties: @@ -849,7 +882,7 @@ paths: - My Notifications requestBody: content: - multipart/form-data: + application/json: schema: type: object properties: @@ -1930,6 +1963,9 @@ paths: type: integer required: - displayName + encoding: + thumbnailfile: + contentType: image/jpeg /video-playlists/{id}: get: @@ -1978,6 +2014,9 @@ paths: videoChannelId: description: Video channel in which the playlist will be published type: integer + encoding: + thumbnailfile: + contentType: image/jpeg delete: summary: Delete a video playlist security: @@ -2242,6 +2281,8 @@ paths: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' + '404': + description: video does not exist requestBody: content: application/json: @@ -2286,6 +2327,8 @@ paths: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' + '404': + description: thread or video does not exist requestBody: content: application/json: @@ -2328,6 +2371,8 @@ paths: responses: '204': description: successful operation + '404': + description: video does not exist /search/videos: get: tags: @@ -2390,6 +2435,9 @@ paths: description: Get videos that have this maximum duration schema: type: integer + callbacks: + 'searchTarget === search-index': + $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation @@ -2397,6 +2445,8 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + '500': + description: search index unavailable /search/video-channels: get: tags: @@ -2416,6 +2466,9 @@ paths: - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/sort' + callbacks: + 'searchTarget === search-index': + $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation @@ -2425,6 +2478,8 @@ paths: type: array items: $ref: '#/components/schemas/VideoChannel' + '500': + description: search index unavailable /blocklist/accounts: get: tags: @@ -3455,6 +3510,7 @@ components: - 1 - 2 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)' + example: 2 VideoStateConstant: properties: @@ -4481,12 +4537,18 @@ components: format: date-time AddUserResponse: properties: - id: - type: integer - uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + user: + type: object + properties: + id: + type: integer + example: 8 + account: + type: object + properties: + id: + type: integer + example: 37 VideoUploadResponse: properties: video: @@ -5156,4 +5218,16 @@ components: type: array maxItems: 100 items: - $ref: '#/components/schemas/Plugin' \ No newline at end of file + $ref: '#/components/schemas/Plugin' + callbacks: + searchIndex: + '{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/api/v1/search/videos/': + post: + summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget` + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoListResponse' \ No newline at end of file