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

@@ -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: [email protected]
+  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