todo-backend: add API schema

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2023-05-06 14:40:43 +02:00
parent 9ab7a4b538
commit 6dad8c08e2
1 changed files with 127 additions and 0 deletions
@@ -0,0 +1,127 @@
+openapi: 3.1.0
+
+info:
+  title: '@backstage/plugin-todo-backend'
+  version: '1'
+  description: The Backstage backend plugin that provides source code todo comment browsing.
+  license:
+    name: Apache-2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  contact: {}
+
+servers:
+  - url: /
+
+components:
+  examples: {}
+  headers: {}
+  parameters: {}
+  requestBodies: {}
+  responses: {}
+  schemas: {}
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /v1/todos:
+    get:
+      operationId: ListTodos
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        text:
+                          type: string
+                          description: The contents of the TODO comment
+                        tag:
+                          type: string
+                          description: The tag used, e.g. TODO, FIXME
+                        author:
+                          type: string
+                          description: References author, if any
+                        viewUrl:
+                          type: string
+                          description: URL used to view the file
+                        lineNumber:
+                          type: integer
+                          description: The line number of the file that the TODO occurs at
+                        repoFilePath:
+                          type: string
+                          description: The path of the file containing the TODO within the repo
+                      required:
+                        - text
+                        - tag
+                      additionalProperties: false
+                  totalCount:
+                    type: integer
+                  offset:
+                    type: integer
+                  limit:
+                    type: integer
+                required:
+                  - items
+                  - totalCount
+                  - offset
+                  - limit
+                additionalProperties: false
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: object
+                    properties:
+                      message:
+                        type: string
+      security:
+        - {}
+        - JWT: []
+      parameters:
+        - name: entity
+          in: query
+          required: true
+          schema:
+            type: string
+            description: A reference to the entity to list TODO items for
+        - name: orderBy
+          in: query
+          required: false
+          schema:
+            type: string
+            pattern: '^(text|tag|author|viewUrl|repoFilePath)=(asc|desc)$'
+            description: The field and direction used to sort the listed TODO items
+        - name: filter
+          in: query
+          required: false
+          schema:
+            type: array
+            description: A list of filters used to narrow down the listed TODO items
+            items:
+              type: string
+              pattern: '^(text|tag|author|viewUrl|repoFilePath)=.+$'
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            description: The offset at which to start listing TODO items
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            description: The number of TODO items to list