From 66f7df0d67b633ccf2c1baebb42c3a4c1b0f4b37 Mon Sep 17 00:00:00 2001 From: Hamza Ali Date: Thu, 10 Sep 2020 08:36:02 +0700 Subject: [PATCH] swagger: add security scheme, improve api semantics --- api/swagger.yaml | 114 ++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 61 deletions(-) diff --git a/api/swagger.yaml b/api/swagger.yaml index 5413ef9..610c49d 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -33,8 +33,8 @@ paths: tags: - Auth Endpoints summary: Logs out a user, making their access token invalid. - requestBody: - $ref: '#/components/requestBodies/TokenRequest' + security: + - token: [] responses: 200: description: You have successfully logged out, and your token is now invalid. @@ -75,7 +75,7 @@ paths: $ref: '#/components/responses/ServerError' /users/{username}: - post: + get: tags: - User Endpoints summary: Get the information for a user. @@ -94,7 +94,7 @@ paths: $ref: '#/components/schemas/User' /users/{username}/posts: - post: + get: tags: - User Endpoints - Post Endpoints @@ -104,9 +104,11 @@ paths: in: path schema: type: string + - $ref: '#/components/parameters/AfterParam' + - $ref: '#/components/parameters/BeforeParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/CountParam' summary: Get the list of posts a user has created/submitted. - requestBody: - $ref: '#/components/requestBodies/Listing' responses: 200: description: A list of posts filtered and formatted. @@ -124,7 +126,7 @@ paths: $ref: '#/components/responses/ServerError' /users/{username}/comments: - post: + get: tags: - User Endpoints - Comments Endpoints @@ -134,9 +136,11 @@ paths: in: path schema: type: string + - $ref: '#/components/parameters/AfterParam' + - $ref: '#/components/parameters/BeforeParam' + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/CountParam' summary: Get the list of comments a user has submitted. - requestBody: - $ref: '#/components/requestBodies/Listing' responses: 200: description: A list of comments filtered and formatted. @@ -157,6 +161,8 @@ paths: post: tags: - Post Endpoints + security: + - token: [] requestBody: description: Submit a new post with this endpoint. required: true @@ -164,18 +170,14 @@ paths: application/json: schema: required: - - token - title properties: - token: - description: The access token. title: description: The title of the post created type: string description: description: The body text of a post, optional. example: - token: abcdef12345678901234 title: I use arch BTW. description: Ladies, I'm waiting. responses: @@ -196,8 +198,41 @@ paths: $ref: '#/components/responses/Unprocessable' 500: $ref: '#/components/responses/ServerError' - components: + parameters: + AfterParam: + name: after + in: query + description: Date after which to return items. + schema: + type: string + format: 'date-time' + example: 2020-01-01T00:00:00.000z + BeforeParam: + name: before + in: query + description: Date before which to return items. + schema: + type: string + format: 'date-time' + example: 2030-01-01T00:00:00.000z + LimitParam: + name: limit + in: query + description: Maximimum number of items to return + schema: + type: integer + maximum: 100 + minimum: 0 + CountParam: + name: count + in: query + description: The number of items already seen in this listing. Items will always be sorted by newest first. + schema: + type: integer + default: 0 + minimum: 0 + requestBodies: AuthCredentials: description: User credentials. @@ -216,24 +251,6 @@ components: password: description: The password of the user. type: string - TokenRequest: - description: The access token to identify a user. - required: true - content: - application/json: - schema: - required: - - token - properties: - token: - description: The access token. - type: string - Listing: - description: Query particular data sorted by date and time. - content: - application/json: - schema: - $ref: '#/components/schemas/Listing' responses: MalformedBody: description: The information in your body is incomplete, or your JSON format is invalid. @@ -398,32 +415,7 @@ components: code: description: The HTTP error code value accompanying the error. type: integer - Listing: - type: object - properties: - after: - description: Filter items to only return those after this date and time. - type: string - format: 'date-time' - default: 2020-01-01T00:00:00.000z - before: - description: Filter items to only return those before this date and time. - type: string - format: 'date-time' - default: 2030-01-01T00:00:00.000z - count: - description: The number of items already seen in this listing. Items will always be sorted by newest first. - type: integer - minimum: 0 - default: 0 - limit: - description: The maximum number of items to provide. Can be used in conjunction with 'count' to paginate. - type: integer - maximum: 100 - minimum: 0 - default: 10 - example: - after: 2020-01-01T00:00:00.000z - before: 2030-01-01T00:00:00.000z - count: 0 - limit: 10 \ No newline at end of file + securitySchemes: + token: + type: http + scheme: bearer \ No newline at end of file