Skip to content

Commit

Permalink
add openapi jsdoc annotation with test (#200)
Browse files Browse the repository at this point in the history 
* add openapi jsdoc annotation with test

* update snap

Co-authored-by: Aras Abbasi <[email protected]>
Co-authored-by: Kalin Chernev <[email protected]>
  • Loading branch information
@Uzlopak @kalinchernev
3 people authored Sep 25, 2020
1 parent e42c894 commit b84f5f7
Show file tree
Hide file tree
Showing 5 changed files with 253 additions and 2 deletions.
2 changes: 1 addition & 1 deletion lib/helpers/filterJsDocComments.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));
}
}
Expand Down
80 changes: 80 additions & 0 deletions test/example/v3/openapi-jsdoc-annotation/api.js
View file
Original file line number Diff line number Diff line change
@@ -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('/', () => {});
};
68 changes: 68 additions & 0 deletions test/example/v3/openapi-jsdoc-annotation/openapi.json
View file
Original file line number Diff line number Diff line change
@@ -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": []
}
8 changes: 7 additions & 1 deletion test/example/v3/test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down
97 changes: 97 additions & 0 deletions test/example/v3/test.js.snap
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down

0 comments on commit b84f5f7

Please sign in to comment.