From ce619f3e56ce1579b5431a7b57600873be7e2994 Mon Sep 17 00:00:00 2001 From: Drew Skwiers-Koballa Date: Tue, 15 Feb 2022 03:20:29 +0000 Subject: [PATCH 1/2] drafting openapi/swagger spec --- data/backend-definition.yaml | 153 +++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 data/backend-definition.yaml diff --git a/data/backend-definition.yaml b/data/backend-definition.yaml new file mode 100644 index 0000000..54816b5 --- /dev/null +++ b/data/backend-definition.yaml @@ -0,0 +1,153 @@ +openapi: 3.0.0 +info: + title: ToDo API + version: 1.0.0 + description: ToDo App API + +components: + schemas: + ToDoItem: + type: object + properties: + id: + type: string + format: uuid + title: + type: string + example: "Learn OpenAPI" + description: + type: string + example: "Learn how to use OpenAPI to create a REST API" + completed: + type: boolean + example: false + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time +paths: + /: + get: + summary: returns a list of the current ToDo items + description: give more information about return type + responses: + '200': + description: a json array of ToDo items + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ToDoItem' + post: + summary: creates a new ToDo item + description: give more information about return type + requestBody: + description: the ToDo item to create + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ToDoItem' + responses: + '200': + description: the created ToDo item + content: + application/json: + schema: + $ref: '#/components/schemas/ToDoItem' + delete: + summary: deletes all ToDo items + description: give more information about return type + responses: + '204': + description: no content + /?id={id}: + get: + summary: returns a single ToDo item + description: give more information about return type + parameters: + - name: id + in: query + description: the id of the ToDo item + required: true + schema: + type: string + format: uuid + responses: + '200': + description: a json object of ToDo item + content: + application/json: + schema: + $ref: '#/components/schemas/ToDoItem' + '404': + description: ToDo item not found + content: + application/json: + schema: + type: array + properties: + message: + type: string + example: "ToDo item not found" + patch: + summary: updates a ToDo item + description: give more information about return type + parameters: + - name: id + in: query + description: the id of the ToDo item + required: true + schema: + type: string + format: uuid + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ToDoItem' + responses: + '200': + description: the updated ToDo item + content: + application/json: + schema: + $ref: '#/components/schemas/ToDoItem' + '404': + description: ToDo item not found + content: + application/json: + schema: + type: array + properties: + message: + type: string + example: "ToDo item not found" + delete: + summary: deletes a single ToDo item + description: give more information about return type + parameters: + - name: id + in: query + description: the id of the ToDo item + required: true + schema: + type: string + format: uuid + responses: + '204': + description: no content + '404': + description: ToDo item not found + content: + application/json: + schema: + type: array + properties: + message: + type: string + example: "ToDo item not found" \ No newline at end of file From 0caee7a27b33440e0e67f6e0e2f882777ef6283a Mon Sep 17 00:00:00 2001 From: Drew Skwiers-Koballa Date: Sat, 5 Mar 2022 03:42:09 +0000 Subject: [PATCH 2/2] completed openAPI spec --- data/backend-definition.yaml | 70 +++++++++++++++--------------------- source/index.html.erb | 2 +- 2 files changed, 29 insertions(+), 43 deletions(-) diff --git a/data/backend-definition.yaml b/data/backend-definition.yaml index 54816b5..1849f19 100644 --- a/data/backend-definition.yaml +++ b/data/backend-definition.yaml @@ -15,23 +15,21 @@ components: title: type: string example: "Learn OpenAPI" - description: - type: string - example: "Learn how to use OpenAPI to create a REST API" + order: + type: integer + example: 2 completed: type: boolean example: false - createdAt: - type: string - format: date-time - updatedAt: + url: type: string - format: date-time + format: uri + example: http://localhost:8080/todo?id=1234-5678-9012-3456 paths: /: get: - summary: returns a list of the current ToDo items - description: give more information about return type + summary: retrieves a list of the current ToDo items + description: returns a list of the current ToDo items responses: '200': description: a json array of ToDo items @@ -43,7 +41,7 @@ paths: $ref: '#/components/schemas/ToDoItem' post: summary: creates a new ToDo item - description: give more information about return type + description: returns the created ToDo item requestBody: description: the ToDo item to create required: true @@ -60,14 +58,20 @@ paths: $ref: '#/components/schemas/ToDoItem' delete: summary: deletes all ToDo items - description: give more information about return type + description: returns the remaining ToDo items (none) responses: - '204': - description: no content + '200': + description: empty array of ToDo items + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ToDoItem' /?id={id}: get: - summary: returns a single ToDo item - description: give more information about return type + summary: retrieve a single ToDo item specified by id + description: returns a single ToDo item parameters: - name: id in: query @@ -85,17 +89,9 @@ paths: $ref: '#/components/schemas/ToDoItem' '404': description: ToDo item not found - content: - application/json: - schema: - type: array - properties: - message: - type: string - example: "ToDo item not found" patch: summary: updates a ToDo item - description: give more information about return type + description: return the updated ToDo item parameters: - name: id in: query @@ -119,17 +115,9 @@ paths: $ref: '#/components/schemas/ToDoItem' '404': description: ToDo item not found - content: - application/json: - schema: - type: array - properties: - message: - type: string - example: "ToDo item not found" delete: summary: deletes a single ToDo item - description: give more information about return type + description: return the remaining ToDo items following the delete operation parameters: - name: id in: query @@ -139,15 +127,13 @@ paths: type: string format: uuid responses: - '204': - description: no content - '404': - description: ToDo item not found + '200': + description: single ToDo item deleted, returns remaining ToDo items content: application/json: schema: type: array - properties: - message: - type: string - example: "ToDo item not found" \ No newline at end of file + items: + $ref: '#/components/schemas/ToDoItem' + '404': + description: ToDo item not found \ No newline at end of file diff --git a/source/index.html.erb b/source/index.html.erb index 56c06f2..8cf741c 100644 --- a/source/index.html.erb +++ b/source/index.html.erb @@ -6,7 +6,7 @@
-

The Todo-Backend project defines a simple web API spec - for managing a todo list. Contributors implement that spec using various tech stacks. Those implementations are cataloged below. A spec runner verifies that each contribution implements the exact same API, by running an automated test suite which defines the API. +

The Todo-Backend project defines a simple web API spec - for managing a todo list. Contributors implement that spec using various tech stacks. Those implementations are cataloged below. A spec runner verifies that each contribution implements the exact same API, by running an automated test suite which defines the API. The API specification is also available as an OpenAPI (Swagger) spec.

The Todo-Backend project was inspired by the TodoMVC project, and some code (specifically the todo client app) was borrowed directly from TodoMVC.