Skip to content

Commit

Permalink
refactor(deps): apidoc update from 0.29.x to 0.5x.x (#207)
Browse files Browse the repository at this point in the history
  • Loading branch information
cdcabrera authored Jan 6, 2023
1 parent 2c40ca9 commit 081e1c4
Show file tree
Hide file tree
Showing 10 changed files with 821 additions and 266 deletions.
9 changes: 5 additions & 4 deletions .eslintrc
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,14 @@
"definedTags": [
"api",
"apiDescription",
"apiHeader",
"apiSuccess",
"apiSuccessExample",
"apiError",
"apiErrorExample",
"apiGroup",
"apiHeader",
"apiMock",
"apiParam"
"apiParam",
"apiSuccess",
"apiSuccessExample"
]
}
],
Expand Down
20 changes: 14 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,14 @@ From there you should be able to navigate to


### Using within a project
**Using ApiDocs**
> The v0.5X.X+ range of ApiDocs, now, requires the description with its updated template (i.e. `@api {get} /hello/world/ [a description]`) if you want the docs to display. If you don't use that aspect of this package you can continue to leave it out.
1. Setup your API annotations first. `@apiSucceessExample` is the only apiDoc example currently implemented.
```js
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiSuccess {String} foo
* @apiSuccess {String} bar
* @apiSuccessExample {json} Success-Response:
Expand All @@ -103,7 +106,8 @@ From there you should be able to navigate to
const getExample = () => {};

/**
* @api {post} /hello/world/
* @api {post} /hello/world/ Post
* @apiGroup Hello World
* @apiHeader {String} Authorization Authorization: Token AUTH_TOKEN
* @apiSuccess {String} foo
* @apiSuccess {String} bar
Expand Down Expand Up @@ -168,7 +172,8 @@ Apidoc Mock adds in a few different custom flags to help you identify or demonst
1. Get random responses from both `success` and `error` examples with the `@apiMock {RandomResponse}` annotation
```js
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiMock {RandomResponse}
* @apiSuccess {String} foo
* @apiSuccess {String} bar
Expand Down Expand Up @@ -199,7 +204,8 @@ Apidoc Mock adds in a few different custom flags to help you identify or demonst
1. Get a random `success` response with the `@apiMock {RandomSuccess}` annotation. Or get a random `error` with the `@apiMock {RandomError}` annotation
```js
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiMock {RandomSuccess}
* @apiSuccess {String} foo
* @apiSuccess {String} bar
Expand Down Expand Up @@ -230,7 +236,8 @@ Apidoc Mock adds in a few different custom flags to help you identify or demonst
1. Force a specific response status with the `@apiMock {ForceStatus} [STATUS GOES HERE]` annotation. If you use a status without a supporting example the response status is still forced, but with fallback content.
```js
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiMock {ForceStatus} 400
* @apiSuccess {String} foo
* @apiSuccess {String} bar
Expand All @@ -255,7 +262,8 @@ Apidoc Mock adds in a few different custom flags to help you identify or demonst
1. Delay a response status with the `@apiMock {DelayResponse} [MILLISECONDS GO HERE]` annotation.
```js
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiMock {DelayResponse} 3000
* @apiSuccess {String} foo
* @apiSuccess {String} bar
Expand Down
15 changes: 10 additions & 5 deletions data/example.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
/**
* @api {get} /hello/world/
* @api {get} /hello/world/ Get
* @apiGroup Hello World
* @apiMock {RandomResponse}
* @apiSuccess {string} foo
* @apiSuccess {string} bar
Expand Down Expand Up @@ -27,7 +28,8 @@
const getExample = () => {};

/**
* @api {post} /hello/world/
* @api {post} /hello/world/ Post
* @apiGroup Hello World
* @apiMock {RandomResponse}
* @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
* @apiSuccess {string} foo
Expand All @@ -48,7 +50,8 @@ const getExample = () => {};
const postExample = () => {};

/**
* @api {put} /hello/world/
* @api {put} /hello/world/ Put
* @apiGroup Hello World
* @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
* @apiSuccess {string} foo
* @apiSuccess {string} bar
Expand All @@ -62,7 +65,8 @@ const postExample = () => {};
const putExample = () => {};

/**
* @api {patch} /hello/world/
* @api {patch} /hello/world/ Patch
* @apiGroup Hello World
* @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
* @apiSuccess {string} foo
* @apiSuccess {string} bar
Expand All @@ -76,7 +80,8 @@ const putExample = () => {};
const patchExample = () => {};

/**
* @api {delete} /hello/world/
* @api {delete} /hello/world/ Delete
* @apiGroup Hello World
* @apiHeader {string} Authorization Authorization: Token AUTH_TOKEN
* @apiSuccess {string} foo
* @apiSuccess {string} bar
Expand Down
8 changes: 7 additions & 1 deletion jest.setupTests.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,13 @@ global.__basedir = __dirname;
*/
const generateFixture = (
contents,
{ dir = resolve(__dirname, '.fixtures'), ext = 'txt', encoding = 'utf8', filename, resetDir = true } = {}
{
dir = resolve(__dirname, '.fixtures'),
ext = 'txt',
encoding = 'utf8',
filename,
resetDir = true
} = {}
) => {
const updatedFileName = filename || crypto.createHash('md5').update(contents).digest('hex');
const file = extname(updatedFileName) ? updatedFileName : `${updatedFileName}.${ext}`;
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@
"description": "API documentation with apiDoc."
},
"dependencies": {
"apidoc": "^0.29.0",
"apidoc": "^0.53.1",
"express": "^4.18.2",
"node-watch": "^0.7.3",
"winston": "^3.8.2",
Expand Down
159 changes: 34 additions & 125 deletions src/__tests__/__snapshots__/index.test.js.snap
Original file line number Diff line number Diff line change
@@ -1,139 +1,48 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`ApiDocMock should create a predictable docs output: setupDocs 1`] = `
exports[`ApiDocMock should handle additional response content types: html mock 1`] = `
{
"error": "{"examples":[{"title":"Error-Response:","content":"HTTP/1.1 400 OK\\n{\\n \\"error\\": \\"test\\"\\n}","type":"json"}]}",
"name": "GetHelloWorld",
"success": "{"examples":[{"title":"Success-Response:","content":"HTTP/1.1 200 OK\\n{\\n \\"success\\": \\"test\\"\\n}","type":"json"}]}",
"error": undefined,
"filename": "html.js",
"group": undefined,
"groupTitle": undefined,
"name": "GetHelloWorldHtmlHtml",
"success": "{"examples":[{"title":"Success-Response:","content":"HTTP/1.1 200 OK\\n<!DOCTYPE html>\\n<html>\\n <head>hello</head>\\n <body>world</body>\\n</html>","type":"html"}]}",
"title": "",
"type": "get",
"url": "/hello/world/",
"url": "/hello/world/html.html",
"version": "0.0.0",
}
`;

exports[`ApiDocMock should create a predictable docs output: specific file output 1`] = `
[
"",
"./.docs/predictable/api_data.js",
"./.docs/predictable/api_data.json",
"./.docs/predictable/api_definition.js",
"./.docs/predictable/api_definition.json",
"./.docs/predictable/api_project.js",
"./.docs/predictable/api_project.json",
"./.docs/predictable/css/style.css",
"./.docs/predictable/fonts/glyphicons-halflings-regular.eot",
"./.docs/predictable/fonts/glyphicons-halflings-regular.svg",
"./.docs/predictable/fonts/glyphicons-halflings-regular.ttf",
"./.docs/predictable/fonts/glyphicons-halflings-regular.woff",
"./.docs/predictable/fonts/glyphicons-halflings-regular.woff2",
"./.docs/predictable/img/android-chrome-192x192.png",
"./.docs/predictable/img/android-chrome-512x512.png",
"./.docs/predictable/img/apple-touch-icon.png",
"./.docs/predictable/img/favicon-16x16.png",
"./.docs/predictable/img/favicon-32x32.png",
"./.docs/predictable/img/favicon.ico",
"./.docs/predictable/index.html",
"./.docs/predictable/locales/ca.js",
"./.docs/predictable/locales/cs.js",
"./.docs/predictable/locales/de.js",
"./.docs/predictable/locales/es.js",
"./.docs/predictable/locales/fr.js",
"./.docs/predictable/locales/it.js",
"./.docs/predictable/locales/locale.js",
"./.docs/predictable/locales/nl.js",
"./.docs/predictable/locales/pl.js",
"./.docs/predictable/locales/pt_br.js",
"./.docs/predictable/locales/ro.js",
"./.docs/predictable/locales/ru.js",
"./.docs/predictable/locales/tr.js",
"./.docs/predictable/locales/vi.js",
"./.docs/predictable/locales/zh.js",
"./.docs/predictable/locales/zh_cn.js",
"./.docs/predictable/main.js",
"./.docs/predictable/utils/handlebars_helper.js",
"./.docs/predictable/utils/send_sample_request.js",
"./.docs/predictable/utils/send_sample_request_utils.js",
"./.docs/predictable/vendor/bootstrap*css",
"./.docs/predictable/vendor/bootstrap*js",
"./.docs/predictable/vendor/diff_match_patch*js",
"./.docs/predictable/vendor/handlebars*js",
"./.docs/predictable/vendor/jquery*js",
"./.docs/predictable/vendor/list*js",
"./.docs/predictable/vendor/lodash*min.js",
"./.docs/predictable/vendor/path-to-regexp/LICENSE",
"./.docs/predictable/vendor/path-to-regexp/index.js",
"./.docs/predictable/vendor/polyfill.js",
"./.docs/predictable/vendor/prism.css",
"./.docs/predictable/vendor/prism.js",
"./.docs/predictable/vendor/require*js",
"./.docs/predictable/vendor/semver*js",
"./.docs/predictable/vendor/webfontloader.js",
]
exports[`ApiDocMock should handle additional response content types: svg mock 1`] = `
{
"error": undefined,
"filename": "svg.js",
"group": undefined,
"groupTitle": undefined,
"name": "GetHelloWorldSvgSvg",
"success": "{"examples":[{"title":"Success-Response:","content":"HTTP/1.1 200 OK\\n<?xml version=\\"1.0\\" encoding=\\"utf-8\\"?>\\n<!DOCTYPE svg PUBLIC \\"-//W3C//DTD SVG 1.1//EN\\" \\"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\\">\\n<svg version=\\"1.1\\" xmlns=\\"http://www.w3.org/2000/svg\\" x=\\"0px\\" y=\\"0px\\" width=\\"10px\\" height=\\"10px\\" viewBox=\\"0 0 10 10\\">\\n<g/>\\n</svg>","type":"svg"}]}",
"title": "",
"type": "get",
"url": "/hello/world/svg.svg",
"version": "0.0.0",
}
`;

exports[`ApiDocMock should handle additional response content types: content-types 1`] = `
[
{
"name": "GetHelloWorldHtmlHtml",
"success": {
"examples": [
{
"content": "HTTP/1.1 200 OK
<!DOCTYPE html>
<html>
<head>hello</head>
<body>world</body>
</html>",
"title": "Success-Response:",
"type": "html",
},
],
},
"title": "",
"type": "get",
"url": "/hello/world/html.html",
"version": "0.0.0",
},
{
"name": "GetHelloWorldSvgSvg",
"success": {
"examples": [
{
"content": "HTTP/1.1 200 OK
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" xmlns="http://www.w3.org/2000/svg" x="0px" y="0px" width="10px" height="10px" viewBox="0 0 10 10">
<g/>
</svg>",
"title": "Success-Response:",
"type": "svg",
},
],
},
"title": "",
"type": "get",
"url": "/hello/world/svg.svg",
"version": "0.0.0",
},
{
"name": "GetHelloWorldTxtTxt",
"success": {
"examples": [
{
"content": "HTTP/1.1 200 OK
hello world",
"title": "Success-Response:",
"type": "unknown",
},
],
},
"title": "",
"type": "get",
"url": "/hello/world/txt.txt",
"version": "0.0.0",
},
]
exports[`ApiDocMock should setup api docs and create a predictable output: setupDocs 1`] = `
{
"error": "{"examples":[{"title":"Error-Response:","content":"HTTP/1.1 400 OK\\n{\\n \\"error\\": \\"test\\"\\n}","type":"json"}]}",
"filename": "test.js",
"group": undefined,
"groupTitle": undefined,
"name": "GetHelloWorld",
"success": "{"examples":[{"title":"Success-Response:","content":"HTTP/1.1 200 OK\\n{\\n \\"success\\": \\"test\\"\\n}","type":"json"}]}",
"title": "",
"type": "get",
"url": "/hello/world/",
"version": "0.0.0",
}
`;

exports[`ApiDocMock should throw an error during testing: error 1`] = `"Server failed to load"`;
Loading

0 comments on commit 081e1c4

Please sign in to comment.