Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/grandlinex/docs-to-openapi
This Project converts comments in your code or in your dependencies to an OpenApi Spec.
https://github.com/grandlinex/docs-to-openapi
documentation grandlinex openapi openapi-specification openapi3 swagger swagger-ui typescript
Last synced: about 2 months ago
JSON representation
This Project converts comments in your code or in your dependencies to an OpenApi Spec.
- Host: GitHub
- URL: https://github.com/grandlinex/docs-to-openapi
- Owner: GrandlineX
- License: bsd-3-clause
- Archived: true
- Created: 2021-08-30T21:45:07.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2021-09-16T19:39:32.000Z (about 3 years ago)
- Last Synced: 2024-09-30T07:02:27.729Z (about 2 months ago)
- Topics: documentation, grandlinex, openapi, openapi-specification, openapi3, swagger, swagger-ui, typescript
- Language: TypeScript
- Homepage:
- Size: 29.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docs to OpenApi v.3
## Documentation
- [Docs](https://grandlinex.github.io/docs/utils/#docs-to-openapi-v3)
[](https://github.com/GrandlineX/docs-to-openapi)
[](https://www.npmjs.com/package/@grandlinex/docs-to-openapi)
## 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
1. Create a `glconf.json` in the root dir of your project (see config 01 or 02).
2. Edit your base Config file like in the official [Swagger Doc](https://swagger.io/specification/)
3. 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
*/
4. 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"
}
}
}
}
}