From 6dad8c08e2c1a6f28edf6d889ea9fe30098c2891 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 6 May 2023 14:40:43 +0200 Subject: [PATCH 1/7] todo-backend: add API schema Signed-off-by: Patrik Oldsberg --- plugins/todo-backend/src/schema/openapi.yaml | 127 +++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 plugins/todo-backend/src/schema/openapi.yaml diff --git a/plugins/todo-backend/src/schema/openapi.yaml b/plugins/todo-backend/src/schema/openapi.yaml new file mode 100644 index 0000000000..2cc56fa773 --- /dev/null +++ b/plugins/todo-backend/src/schema/openapi.yaml @@ -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 From 120255b3c93e9e7953e8f5552a0009aa6dc085e1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 9 May 2023 12:04:22 +0200 Subject: [PATCH 2/7] todo-backend: generate and use API schema Signed-off-by: Patrik Oldsberg --- plugins/todo-backend/package.json | 1 + .../src/schema/openapi.generated.ts | 202 ++++++++++++++++++ plugins/todo-backend/src/service/router.ts | 4 +- yarn.lock | 1 + 4 files changed, 207 insertions(+), 1 deletion(-) create mode 100644 plugins/todo-backend/src/schema/openapi.generated.ts diff --git a/plugins/todo-backend/package.json b/plugins/todo-backend/package.json index d98a44f874..4dc0ec9dbb 100644 --- a/plugins/todo-backend/package.json +++ b/plugins/todo-backend/package.json @@ -30,6 +30,7 @@ }, "dependencies": { "@backstage/backend-common": "workspace:^", + "@backstage/backend-openapi-utils": "workspace:^", "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-client": "workspace:^", "@backstage/catalog-model": "workspace:^", diff --git a/plugins/todo-backend/src/schema/openapi.generated.ts b/plugins/todo-backend/src/schema/openapi.generated.ts new file mode 100644 index 0000000000..503881d975 --- /dev/null +++ b/plugins/todo-backend/src/schema/openapi.generated.ts @@ -0,0 +1,202 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +// ****************************************************************** +// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. * +// ****************************************************************** + +export default { + 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', + }, + }, + ], + }, + }, + }, +} as const; diff --git a/plugins/todo-backend/src/service/router.ts b/plugins/todo-backend/src/service/router.ts index 5954fab009..e84dfcc58e 100644 --- a/plugins/todo-backend/src/service/router.ts +++ b/plugins/todo-backend/src/service/router.ts @@ -25,6 +25,8 @@ import { parseIntegerParam, parseOrderByParam, } from '../lib/utils'; +import spec from '../schema/openapi.generated'; +import { ApiRouter } from '@backstage/backend-openapi-utils'; /** @public */ export interface RouterOptions { @@ -37,7 +39,7 @@ export async function createRouter( ): Promise { const { todoService } = options; - const router = Router(); + const router = Router() as ApiRouter; router.use(express.json()); router.get('/v1/todos', async (req, res) => { diff --git a/yarn.lock b/yarn.lock index 7f2307e92c..70d49f9484 100644 --- a/yarn.lock +++ b/yarn.lock @@ -9567,6 +9567,7 @@ __metadata: resolution: "@backstage/plugin-todo-backend@workspace:plugins/todo-backend" dependencies: "@backstage/backend-common": "workspace:^" + "@backstage/backend-openapi-utils": "workspace:^" "@backstage/backend-plugin-api": "workspace:^" "@backstage/catalog-client": "workspace:^" "@backstage/catalog-model": "workspace:^" From 901f1ada32525edbd2a7e5813d2cdb6778ef54a1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 9 May 2023 13:46:16 +0200 Subject: [PATCH 3/7] changesets: add changeset for todo-backend API schema Signed-off-by: Patrik Oldsberg --- .changeset/honest-comics-ring.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/honest-comics-ring.md diff --git a/.changeset/honest-comics-ring.md b/.changeset/honest-comics-ring.md new file mode 100644 index 0000000000..38a962c5d3 --- /dev/null +++ b/.changeset/honest-comics-ring.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-todo-backend': patch +--- + +Added OpenAPI schema From b81adf8ed8164110071dcbfd260561ed88eaa24a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 10 May 2023 11:04:56 +0200 Subject: [PATCH 4/7] todo-backend: switch OpenApi schema to 3.0.3 Signed-off-by: Patrik Oldsberg --- plugins/todo-backend/src/schema/openapi.generated.ts | 2 +- plugins/todo-backend/src/schema/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/todo-backend/src/schema/openapi.generated.ts b/plugins/todo-backend/src/schema/openapi.generated.ts index 503881d975..daf17285b4 100644 --- a/plugins/todo-backend/src/schema/openapi.generated.ts +++ b/plugins/todo-backend/src/schema/openapi.generated.ts @@ -19,7 +19,7 @@ // ****************************************************************** export default { - openapi: '3.1.0', + openapi: '3.0.3', info: { title: '@backstage/plugin-todo-backend', version: '1', diff --git a/plugins/todo-backend/src/schema/openapi.yaml b/plugins/todo-backend/src/schema/openapi.yaml index 2cc56fa773..19051c00d3 100644 --- a/plugins/todo-backend/src/schema/openapi.yaml +++ b/plugins/todo-backend/src/schema/openapi.yaml @@ -1,4 +1,4 @@ -openapi: 3.1.0 +openapi: 3.0.3 info: title: '@backstage/plugin-todo-backend' From f41881c6232fe32f504a8c63e4122dc2c1ae1abb Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 10 May 2023 11:07:00 +0200 Subject: [PATCH 5/7] todo-backend: move openapi-utils to dev deps Signed-off-by: Patrik Oldsberg --- plugins/todo-backend/package.json | 2 +- plugins/todo-backend/src/service/router.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/todo-backend/package.json b/plugins/todo-backend/package.json index 4dc0ec9dbb..9385ec0ee6 100644 --- a/plugins/todo-backend/package.json +++ b/plugins/todo-backend/package.json @@ -30,7 +30,6 @@ }, "dependencies": { "@backstage/backend-common": "workspace:^", - "@backstage/backend-openapi-utils": "workspace:^", "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-client": "workspace:^", "@backstage/catalog-model": "workspace:^", @@ -46,6 +45,7 @@ "yn": "^4.0.0" }, "devDependencies": { + "@backstage/backend-openapi-utils": "workspace:^", "@backstage/cli": "workspace:^", "@types/supertest": "^2.0.8", "msw": "^1.0.0", diff --git a/plugins/todo-backend/src/service/router.ts b/plugins/todo-backend/src/service/router.ts index e84dfcc58e..364cbef6b0 100644 --- a/plugins/todo-backend/src/service/router.ts +++ b/plugins/todo-backend/src/service/router.ts @@ -26,7 +26,7 @@ import { parseOrderByParam, } from '../lib/utils'; import spec from '../schema/openapi.generated'; -import { ApiRouter } from '@backstage/backend-openapi-utils'; +import type { ApiRouter } from '@backstage/backend-openapi-utils'; /** @public */ export interface RouterOptions { From 1bf5f1e3764f420586a7d4bbd83d3fa588953cb2 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 10 May 2023 11:09:57 +0200 Subject: [PATCH 6/7] todo-backend: add additional basic constraints to API schema Signed-off-by: Patrik Oldsberg --- plugins/todo-backend/src/schema/openapi.generated.ts | 3 +++ plugins/todo-backend/src/schema/openapi.yaml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/plugins/todo-backend/src/schema/openapi.generated.ts b/plugins/todo-backend/src/schema/openapi.generated.ts index daf17285b4..0ef39a4054 100644 --- a/plugins/todo-backend/src/schema/openapi.generated.ts +++ b/plugins/todo-backend/src/schema/openapi.generated.ts @@ -149,6 +149,7 @@ export default { required: true, schema: { type: 'string', + minLength: 1, description: 'A reference to the entity to list TODO items for', }, }, @@ -183,6 +184,7 @@ export default { required: false, schema: { type: 'integer', + minimum: 0, description: 'The offset at which to start listing TODO items', }, }, @@ -192,6 +194,7 @@ export default { required: false, schema: { type: 'integer', + minimum: 1, description: 'The number of TODO items to list', }, }, diff --git a/plugins/todo-backend/src/schema/openapi.yaml b/plugins/todo-backend/src/schema/openapi.yaml index 19051c00d3..b16b0bbf2a 100644 --- a/plugins/todo-backend/src/schema/openapi.yaml +++ b/plugins/todo-backend/src/schema/openapi.yaml @@ -96,6 +96,7 @@ paths: required: true schema: type: string + minLength: 1 description: A reference to the entity to list TODO items for - name: orderBy in: query @@ -118,10 +119,12 @@ paths: required: false schema: type: integer + minimum: 0 description: The offset at which to start listing TODO items - name: limit in: query required: false schema: type: integer + minimum: 1 description: The number of TODO items to list From b61788b0a32aafb0b71eed54c8bcfb3359dfdf51 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 10 May 2023 11:40:19 +0200 Subject: [PATCH 7/7] todo-backend: separate TodoItem declaration in API schema Signed-off-by: Patrik Oldsberg --- .../src/schema/openapi.generated.ts | 67 ++++++++++--------- plugins/todo-backend/src/schema/openapi.yaml | 52 +++++++------- 2 files changed, 62 insertions(+), 57 deletions(-) diff --git a/plugins/todo-backend/src/schema/openapi.generated.ts b/plugins/todo-backend/src/schema/openapi.generated.ts index 0ef39a4054..54486a5615 100644 --- a/plugins/todo-backend/src/schema/openapi.generated.ts +++ b/plugins/todo-backend/src/schema/openapi.generated.ts @@ -42,7 +42,40 @@ export default { parameters: {}, requestBodies: {}, responses: {}, - schemas: {}, + schemas: { + TodoItem: { + 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, + }, + }, securitySchemes: { JWT: { type: 'http', @@ -66,37 +99,7 @@ export default { 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, + $ref: '#/components/schemas/TodoItem', }, }, totalCount: { diff --git a/plugins/todo-backend/src/schema/openapi.yaml b/plugins/todo-backend/src/schema/openapi.yaml index b16b0bbf2a..3fba129644 100644 --- a/plugins/todo-backend/src/schema/openapi.yaml +++ b/plugins/todo-backend/src/schema/openapi.yaml @@ -18,7 +18,32 @@ components: parameters: {} requestBodies: {} responses: {} - schemas: {} + schemas: + TodoItem: + 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 securitySchemes: JWT: type: http @@ -39,30 +64,7 @@ paths: 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 + $ref: '#/components/schemas/TodoItem' totalCount: type: integer offset: