@grandlinex/docs-to-openapi
v0.6.0
Published
OpenApiTag to OpenapiSpec
Downloads
12
Maintainers
Readme
Docs to OpenApi v.3
Documentation
Description
This Project converts comments in your code or in your dependencies to an OpenApi Spec. The following annotations are supported.
@openapi
@swagger
All comments with these annotations will be pasted as a singe element in the path definition array.
For all other OpenApi configs the glconf.json
is used.
Installation
npm i -g @grandlinex/docs-to-openapi
Config fields
- rootDir
- Relative path to your sourcecode.
- filetypes
- List of file extensions to monitor.
- externalModules
- If your dependencies use also these annotations you can merge these in your curren spec.
- outPutDir (optional)
- Relative path for the Spec. output.
Quick Start
Create a
glconf.json
in the root dir of your project (see config 01 or 02).Edit your base Config file like in the official Swagger Doc
Add a Comment to your soruce code in yml syntax like:
/** * @openapi * /ping: * get: * summary: ping * tags: * - basic * responses: * 200: * description: OK * 401: * description: not authorized */
run
npx @grandlinex/docs-to-openapi
If you install the package as a dependency or global then you can use the
makeOpenApi
command.
CLI Parameter
|Parameter|Description|
|---|---|
|--html
|Creates a swagger.html file (Standalone SwaggerUI)|
|--serve
|Serves the OpenApi Spec on port 9000|
Config File Examples:
Config 01 glconf.json
(minimal)
{
"rootDir": "./src",
"filetypes": ["ts","js"],
"externalModules": [],
"baseConfig": {
"info": {
"title": "Hello World",
"version": "1.0.0",
"description": "A sample API"
},
"servers": [
{
"url": "http://localhost:9257"
}
]
}
}
Config 02 glconf.json
(Bearer JWT)
{
"rootDir": "./src",
"filetypes": ["ts","js"],
"externalModules": ["./node_modules/module_a","./node_modules/module_b"],
"outPutDir": "./dist",
"baseConfig": {
"info": {
"title": "Hello World",
"version": "1.0.0",
"description": "A sample API"
},
"servers": [
{
"url": "http://localhost:9257"
}
],
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}
}