api-spec-helper is a CLI tool meant to help you generate API documentation based on the OAS3.
It generates simple stubs for user-specified paths, allowing you to add methods and responses to your requests automatically. You will still need to customize requestBody properties, request parameters and response schemas. You will also need to fix the indentation in some parts, unfortunately.
It is currently in the early stages of development, and only supports JSON formatting.
Install globally on your computer:
npm install -g api-spec-helperRun api-spec-helper --help to get a list of commands and arguments.
api-spec-helper command references:
-h --help Display this help message.
-a --add-path Adds routes to specific paths. Expects arguments:
-p --paths=users,estates Specify which paths will be documented.
-t --tag='Admin Panel' Specify a single tag to the generated paths.
-m --methods=GET,PUT,DELETE Specify which methods will be generated. Defaults to all 4.
-r --responses=200,203 Specify HTTP status codes for responses. Defaults to 200, 204, 401 & 404.
-g --generate-stub Generate barebones OAS3 file. Accepts the following arguments:
-t --tag='Admin,Customer' Specify your project's tags, which will be referenced in your paths. Comma-separated.
-n --name='Application' Specify your application's title. api-spec-helper -g -t 'Admin Panel'will be equivalent to
api-spec-helper --generate-stub --tag 'Admin Panel'and will generate the following json in stdout:
{
"openapi": "3.0.0",
"info": {
"version": "0.1.0",
"title": "Application Title",
"description": "Application Description"
},
"servers": [
{
"url": "http://localhost",
"description": "Your local application server"
}
],
"tags": [
{"name": "Admin Panel", "description": "Tag description"}
],
"paths": {
api-spec-helper -a -p users,estates -t 'Admin Panel' -m GET,POST -r 200will be equivalent to
api-spec-helper --add-path --paths=users,estates --tag='Admin Panel' --methods=GET,POST --responses=200and will generate the following json in stdout:
"/users": {
"get": {
"tags": ["Admin Panel"],
"summary": "",
"responses": {
"200": {"description": "OK"}
}
},
"post": {
"tags": ["Admin Panel"],
"summary": "",
"requestBody": {
"description": "",
"content": {
}
},
"responses": {
"200": {"description": "OK"}
}
}
},
"/estates": {
"get": {
"tags": ["Admin Panel"],
"summary": "",
"responses": {
"200": {"description": "OK"}
}
},
"post": {
"tags": ["Admin Panel"],
"summary": "",
"requestBody": {
"description": "",
"content": {
}
},
"responses": {
"200": {"description": "OK"}
}
}
},You can choose to send your output for a specific text file or simply copy-paste the stubs on your swagger.json file. Then, adapt and add content as necessary.
Please visit the Contributing Guide.
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent