Created
October 7, 2021 02:10
-
-
Save pietrotavares/b6e434f9216a2631ebf0a8c966d46084 to your computer and use it in GitHub Desktop.
Sample OpenAPI v3 spec file
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| openapi: 3.0.3 | |
| info: | |
| title: REST-API-001 | |
| description: >- | |
| The purpose of this kata is to give an overall understanding of a | |
| backend application. You’ll be implementing a simplified version of a news | |
| provider API. | |
| This is an all around kata that cover both juniors and experience devs | |
| based on the depth of how the concepts were applied. | |
| contact: | |
| name: Pietro Tavares | |
| url: https://www.github.com/pietrotavares/katas/solutions/REST-API-001 | |
| license: | |
| name: 'License: MIT' | |
| url: https://opensource.org/licenses/MIT | |
| version: 0.1.0 | |
| components: | |
| securitySchemes: | |
| JWT: | |
| type: http | |
| scheme: bearer | |
| bearerFormat: JWT | |
| schemas: | |
| AuthCredentials: | |
| type: object | |
| properties: | |
| username: | |
| type: string | |
| password: | |
| type: string | |
| AuthorWrite: | |
| type: object | |
| properties: | |
| name: | |
| type: string | |
| picture: | |
| type: string | |
| AuthorRead: | |
| allOf: | |
| - $ref: '#/components/schemas/AuthorWrite' | |
| - type: object | |
| properties: | |
| id: | |
| type: string | |
| ArticleOverview: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| author: | |
| $ref: '#/components/schemas/AuthorRead' | |
| title: | |
| type: string | |
| category: | |
| type: string | |
| summary: | |
| type: string | |
| ArticleOverviewList: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/ArticleOverview' | |
| ArticlePreview: | |
| allOf: | |
| - $ref: '#/components/schemas/ArticleOverview' | |
| - type: object | |
| properties: | |
| firstParagraph: | |
| type: string | |
| ArticleRead: | |
| allOf: | |
| - $ref: '#/components/schemas/ArticlePreview' | |
| - type: object | |
| properties: | |
| author: | |
| $ref: '#/components/schemas/AuthorRead' | |
| - type: object | |
| properties: | |
| body: | |
| type: string | |
| ArticleWrite: | |
| type: object | |
| properties: | |
| author: | |
| type: string | |
| title: | |
| type: string | |
| category: | |
| type: string | |
| summary: | |
| type: string | |
| firstParagraph: | |
| type: string | |
| body: | |
| type: string | |
| paths: | |
| /api/sign-up/: | |
| post: | |
| summary: Sign up for an account (create a new user) | |
| tags: [Auth] | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| allOf: | |
| - $ref: '#/components/schemas/AuthCredentials' | |
| - type: object | |
| properties: | |
| email: | |
| type: string | |
| responses: | |
| '201': | |
| description: Successfully created a new user | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| username: | |
| type: string | |
| email: | |
| type: string | |
| '400': | |
| description: Bad request | |
| '500': | |
| description: Internal server error | |
| /api/login/: | |
| post: | |
| summary: Log in using an account | |
| tags: [Auth] | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/AuthCredentials' | |
| responses: | |
| '200': | |
| description: Successfully logged in (JWT Tokens retrieved) | |
| content: | |
| application/json: | |
| schema: | |
| type: object | |
| properties: | |
| refresh: | |
| type: string | |
| access: | |
| type: string | |
| '400': | |
| description: Bad request | |
| '401': | |
| description: Unauthorized | |
| '500': | |
| description: Internal server error | |
| /api/admin/authors/: | |
| post: | |
| summary: Add a new author | |
| tags: [Authors, Admin] | |
| security: | |
| - JWT: [] | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/AuthorWrite' | |
| responses: | |
| '201': | |
| description: Successfully added a new author | |
| content: | |
| application/json: | |
| schema: | |
| allOf: | |
| - $ref: '#/components/schemas/AuthorRead' | |
| - type: object | |
| properties: | |
| id: | |
| type: string | |
| '400': | |
| description: Bad request | |
| '401': | |
| description: Unauthorized | |
| '500': | |
| description: Internal server error | |
| /api/admin/authors/{id}/: | |
| get: | |
| summary: Retrieve an author | |
| tags: [Authors, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the author to get | |
| responses: | |
| '200': | |
| description: Successfully retrieved the author | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/AuthorRead' | |
| '400': | |
| description: Bad request | |
| '401': | |
| description: Unauthorized | |
| '404': | |
| description: Author was not found | |
| '500': | |
| description: INTERNAL_SERVER_ERROR | |
| put: | |
| summary: Update an author | |
| tags: [Authors, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the author to update | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/AuthorWrite' | |
| responses: | |
| '200': | |
| description: Successfully updated the author | |
| content: | |
| application/json: | |
| schema: | |
| allOf: | |
| - $ref: '#/components/schemas/AuthorRead' | |
| '400': | |
| description: Bad request | |
| '401': | |
| description: Unauthorized | |
| '404': | |
| description: Author was not found | |
| '500': | |
| description: Internal server error | |
| delete: | |
| summary: Remove an author | |
| tags: [Authors, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the author to remove | |
| responses: | |
| '204': | |
| description: No content (successfully removed the author) | |
| '400': | |
| description: Bad request | |
| '401': | |
| description: Unauthorized | |
| '404': | |
| description: Author was not found | |
| '500': | |
| description: Internal server error | |
| /api/admin/articles/: | |
| get: | |
| summary: List all articles | |
| description: Articles are presented in Overview format | |
| tags: [Articles, Admin] | |
| security: | |
| - JWT: [] | |
| responses: | |
| '200': | |
| description: Succesfully returned a list of articles overviews | |
| content: | |
| aplication/json: | |
| schema: | |
| allOf: | |
| - $ref: '#/components/schemas/ArticleOverviewList' | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: No articles were found | |
| '500': | |
| description: Internal server error | |
| post: | |
| summary: Add a new article | |
| tags: [Articles, Admin] | |
| security: | |
| - JWT: [] | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleWrite' | |
| responses: | |
| '201': | |
| description: Successfully added a new article | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleRead' | |
| '400': | |
| description: Invalid request | |
| '500': | |
| description: Internal server error | |
| /api/admin/articles/{id}/: | |
| get: | |
| summary: Retrieve an article | |
| tags: [Articles, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the article to get | |
| responses: | |
| '200': | |
| description: Successfully retrieved the article | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleRead' | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: Article was not found | |
| '500': | |
| description: Internal server error | |
| put: | |
| summary: Update an article | |
| tags: [Articles, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the article to update | |
| requestBody: | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleWrite' | |
| responses: | |
| '200': | |
| description: Successfully updated the article | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleRead' | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: Article was not found | |
| '500': | |
| description: Internal server error | |
| delete: | |
| summary: Remove an article | |
| tags: [Articles, Admin] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the article to delete | |
| responses: | |
| '204': | |
| description: No content | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: Article was not found | |
| '500': | |
| description: Internal server error | |
| /api/articles/: | |
| get: | |
| summary: List all articles | |
| description: Articles are presented in Overview format | |
| tags: [Articles, Public] | |
| security: | |
| - JWT: [] | |
| responses: | |
| '200': | |
| description: Succesfully returned a list of articles overviews | |
| content: | |
| aplication/json: | |
| schema: | |
| allOf: | |
| - $ref: '#/components/schemas/ArticleOverviewList' | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: No articles were found | |
| '500': | |
| description: Internal server error | |
| /api/articles/{id}/: | |
| get: | |
| summary: Retrieve an article | |
| description: Responses to requests made by anonymous users do not include the 'body' field. The response shown below considers a logged in user. | |
| tags: [Articles, Public] | |
| security: | |
| - JWT: [] | |
| parameters: | |
| - in: path | |
| name: id | |
| schema: | |
| type: string | |
| required: true | |
| description: Id of the article to get | |
| responses: | |
| '200': | |
| description: Successfully retrieved the article | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ArticleRead' | |
| '400': | |
| description: Bad request | |
| '404': | |
| description: Article was not found | |
| '500': | |
| description: Internal server error |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment