From b23de3399793aea5e2839d8faa6527318469a21a Mon Sep 17 00:00:00 2001 From: James Higginbotham Date: Thu, 3 Oct 2024 11:23:20 -0600 Subject: [PATCH] Add todo-example-openapi-source.yaml Added an example TODO API that was part of the "Writing an OpenAPI Document from the Ground Up" guide --- apis/todo-example-openapi-source.yaml | 189 ++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 apis/todo-example-openapi-source.yaml diff --git a/apis/todo-example-openapi-source.yaml b/apis/todo-example-openapi-source.yaml new file mode 100644 index 0000000..9c26260 --- /dev/null +++ b/apis/todo-example-openapi-source.yaml @@ -0,0 +1,189 @@ +openapi: 3.0.0 +info: + title: Personal TODO List API + version: 1.0.0 + description: + This API allows an individual to manage a simple list of tasks. + + Tasks have a status of 'new' when first created and should be moved to 'in progress' when the task has begun and 'completed' once the task is finished. + contact: + email: api-support@todolist.local + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + termsOfService: https://onlinestore.com/terms +servers: + - url: 'https://api.todolist.local/v1' +tags: + - name: Manage Tasks + description: Supports task management such as adding, updating, and deleting tasks + - name: View Tasks + description: Lists all tasks or retrieves the details for a specific task +paths: + /tasks: + get: + summary: List available tasks on the TODO list + description: + Lists tasks that have been created, with a default filter of 'new' and 'in progress' tasks unless specified otherwise + operationId: listTasks + tags: + - View Tasks + security: + - oauth2: + - task:read + parameters: + - name: status + in: query + required: false + description: Filters the list of tasks by the status provided + schema: + type: string + example: 'completed' + responses: + '200': + description: Returns a list of Tasks, with any request filters applied + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Task' + examples: + tasks: + value: + - id: 1 + description: "Buy milk" + status: "completed" + - id: 2 + description: "Send email to John" + status: "in progress" + post: + summary: Add a new task to the TODO list + description: + Adds a new task to the TODO list and sets the status to 'new' + operationId: addTask + tags: + - Manage Tasks + security: + - oauth2: + - task:create + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + examples: + task: + value: + id: 3 + description: "Read a book" + status: "new" + /tasks/{taskId}: + parameters: + - name: taskId + in: path + required: true + description: The ID of the task to operate on + schema: + type: integer + example: 3 + get: + summary: Retrieve the details for a task on the TODO list + description: + Returns the details for a task from the TODO list by identifier + operationId: getTask + tags: + - View Tasks + security: + - oauth2: + - task:read + responses: + '200': + description: Returns the details of the retrieved task + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + examples: + task: + value: + id: 3 + description: "Read a book" + status: "new" + delete: + summary: Remove a task from the TODO list + description: + Permanently removes a task from the TODO list. If a task was completed, use `PUT /tasks/{taskId}` to update its status to 'completed' + operationId: removeTask + tags: + - Manage Tasks + security: + - oauth2: + - task:delete + responses: + '204': + description: Task deleted successfully + '404': + description: Task not found by the ID provided + put: + summary: Update a task on the TODO list + description: + Updates a specific task's details and/or status + operationId: updateTask + tags: + - Manage Tasks + security: + - oauth2: + - task:update + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + responses: + '200': + description: Task updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '404': + description: Task not found by the ID provided +components: + schemas: + Task: + type: object + description: Represents a task with a status indicating its progression. + properties: + id: + type: integer + description: The unique identifier for a task. + example: 1 + description: + type: string + description: A brief summary of the task. + example: "Buy milk" + status: + type: string + description: The current status of the task, which can be 'new', 'in progress', or 'completed'. + enum: + - new + - in progress + - completed + default: new + example: "new" + securitySchemes: + oauth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://api.todolist.local/oauth/authorize + tokenUrl: https://api.todolist.local/oauth/token + scopes: + task:read: Authorization to Read tasks + task:create: Authorization to Create tasks + task:update: Authorization to Update tasks + task:delete: Authorization to Delete tasks