From b84f5f734d79683afcd62520fd2fa4df4d95509d Mon Sep 17 00:00:00 2001 From: Uzlopak Date: Fri, 25 Sep 2020 12:47:29 +0200 Subject: [PATCH] add openapi jsdoc annotation with test (#200) * add openapi jsdoc annotation with test * update snap Co-authored-by: Aras Abbasi Co-authored-by: Kalin Chernev --- lib/helpers/filterJsDocComments.js | 2 +- .../v3/openapi-jsdoc-annotation/api.js | 80 +++++++++++++++ .../v3/openapi-jsdoc-annotation/openapi.json | 68 +++++++++++++ test/example/v3/test.js | 8 +- test/example/v3/test.js.snap | 97 +++++++++++++++++++ 5 files changed, 253 insertions(+), 2 deletions(-) create mode 100644 test/example/v3/openapi-jsdoc-annotation/api.js create mode 100644 test/example/v3/openapi-jsdoc-annotation/openapi.json diff --git a/lib/helpers/filterJsDocComments.js b/lib/helpers/filterJsDocComments.js index 97d732bd..8e742edb 100644 --- a/lib/helpers/filterJsDocComments.js +++ b/lib/helpers/filterJsDocComments.js @@ -14,7 +14,7 @@ function filterJsDocComments(jsDocComments) { const jsDocComment = jsDocComments[i]; for (let j = 0; j < jsDocComment.tags.length; j += 1) { const tag = jsDocComment.tags[j]; - if (tag.title === 'swagger') { + if (tag.title === 'swagger' || tag.title === 'openapi') { swaggerJsDocComments.push(jsYaml.safeLoad(tag.description)); } } diff --git a/test/example/v3/openapi-jsdoc-annotation/api.js b/test/example/v3/openapi-jsdoc-annotation/api.js new file mode 100644 index 00000000..49cb28a0 --- /dev/null +++ b/test/example/v3/openapi-jsdoc-annotation/api.js @@ -0,0 +1,80 @@ +// Imaginary API helper +module.exports = function (app) { + /** + * @openapi + * + * /: + * get: + * operationId: listVersionsv2 + * summary: List API versions + * responses: + * '200': + * description: |- + * 200 response + * content: + * application/json: + * examples: + * foo: + * value: { + * "versions": [ + * { + * "status": "CURRENT", + * "updated": "2011-01-21T11:33:21Z", + * "id": "v2.0", + * "links": [ + * { + * "href": "http://127.0.0.1:8774/v2/", + * "rel": "self" + * } + * ] + * }, + * { + * "status": "EXPERIMENTAL", + * "updated": "2013-07-23T11:33:21Z", + * "id": "v3.0", + * "links": [ + * { + * "href": "http://127.0.0.1:8774/v3/", + * "rel": "self" + * } + * ] + * } + * ] + * } + * '300': + * description: |- + * 300 response + * content: + * application/json: + * examples: + * foo: + * value: | + * { + * "versions": [ + * { + * "status": "CURRENT", + * "updated": "2011-01-21T11:33:21Z", + * "id": "v2.0", + * "links": [ + * { + * "href": "http://127.0.0.1:8774/v2/", + * "rel": "self" + * } + * ] + * }, + * { + * "status": "EXPERIMENTAL", + * "updated": "2013-07-23T11:33:21Z", + * "id": "v3.0", + * "links": [ + * { + * "href": "http://127.0.0.1:8774/v3/", + * "rel": "self" + * } + * ] + * } + * ] + * } + */ + app.get('/', () => {}); +}; diff --git a/test/example/v3/openapi-jsdoc-annotation/openapi.json b/test/example/v3/openapi-jsdoc-annotation/openapi.json new file mode 100644 index 00000000..25f27fd4 --- /dev/null +++ b/test/example/v3/openapi-jsdoc-annotation/openapi.json @@ -0,0 +1,68 @@ +{ + "openapi": "3.0.0", + "info": { + "version": "1.0.0", + "title": "Sample specification testing openapi-jsdoc-annotation" + }, + "paths": { + "/": { + "get": { + "operationId": "listVersionsv2", + "summary": "List API versions", + "responses": { + "200": { + "description": "200 response", + "content": { + "application/json": { + "examples": { + "foo": { + "value": { + "versions": [ + { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "id": "v2.0", + "links": [ + { + "href": "http://127.0.0.1:8774/v2/", + "rel": "self" + } + ] + }, + { + "status": "EXPERIMENTAL", + "updated": "2013-07-23T11:33:21Z", + "id": "v3.0", + "links": [ + { + "href": "http://127.0.0.1:8774/v3/", + "rel": "self" + } + ] + } + ] + } + } + } + } + } + }, + "300": { + "description": "300 response", + "content": { + "application/json": { + "examples": { + "foo": { + "value": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}\n" + } + } + } + } + } + } + } + } + }, + "components": {}, + "tags": [] +} diff --git a/test/example/v3/test.js b/test/example/v3/test.js index fee217da..fd1959bc 100644 --- a/test/example/v3/test.js +++ b/test/example/v3/test.js @@ -18,7 +18,13 @@ beforeEach(function () { chaiJestSnapshot.configureUsingMochaContext(this); }); -const tests = ['api-with-examples', 'callback', 'links', 'petstore']; +const tests = [ + 'api-with-examples', + 'callback', + 'links', + 'petstore', + 'openapi-jsdoc-annotation', +]; describe('OpenAPI examples', () => { tests.forEach((test) => { diff --git a/test/example/v3/test.js.snap b/test/example/v3/test.js.snap index 1a17bcc6..b26107bd 100644 --- a/test/example/v3/test.js.snap +++ b/test/example/v3/test.js.snap @@ -259,6 +259,103 @@ Object { } `; +exports[`OpenAPI examples Example: openapi-jsdoc-annotation 1`] = ` +Object { + "components": Object {}, + "info": Object { + "title": "Sample specification testing openapi-jsdoc-annotation", + "version": "1.0.0", + }, + "openapi": "3.0.0", + "paths": Object { + "/": Object { + "get": Object { + "operationId": "listVersionsv2", + "responses": Object { + "200": Object { + "content": Object { + "application/json": Object { + "examples": Object { + "foo": Object { + "value": Object { + "versions": Array [ + Object { + "id": "v2.0", + "links": Array [ + Object { + "href": "http://127.0.0.1:8774/v2/", + "rel": "self", + }, + ], + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + }, + Object { + "id": "v3.0", + "links": Array [ + Object { + "href": "http://127.0.0.1:8774/v3/", + "rel": "self", + }, + ], + "status": "EXPERIMENTAL", + "updated": "2013-07-23T11:33:21Z", + }, + ], + }, + }, + }, + }, + }, + "description": "200 response", + }, + "300": Object { + "content": Object { + "application/json": Object { + "examples": Object { + "foo": Object { + "value": "{ + \\"versions\\": [ + { + \\"status\\": \\"CURRENT\\", + \\"updated\\": \\"2011-01-21T11:33:21Z\\", + \\"id\\": \\"v2.0\\", + \\"links\\": [ + { + \\"href\\": \\"http://127.0.0.1:8774/v2/\\", + \\"rel\\": \\"self\\" + } + ] + }, + { + \\"status\\": \\"EXPERIMENTAL\\", + \\"updated\\": \\"2013-07-23T11:33:21Z\\", + \\"id\\": \\"v3.0\\", + \\"links\\": [ + { + \\"href\\": \\"http://127.0.0.1:8774/v3/\\", + \\"rel\\": \\"self\\" + } + ] + } + ] +} +", + }, + }, + }, + }, + "description": "300 response", + }, + }, + "summary": "List API versions", + }, + }, + }, + "tags": Array [], +} +`; + exports[`OpenAPI examples Example: petstore 1`] = ` Object { "components": Object {