Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/open-template-hub/swagger-decorators
OTH library that contains methods and decorators to ease and automate Swagger documentation.
https://github.com/open-template-hub/swagger-decorators
decorators swagger swagger-codegen swagger-decorators swagger-documentation swagger-ui swagger-ui-express template
Last synced: 21 days ago
JSON representation
OTH library that contains methods and decorators to ease and automate Swagger documentation.
- Host: GitHub
- URL: https://github.com/open-template-hub/swagger-decorators
- Owner: open-template-hub
- License: mit
- Created: 2022-11-14T17:16:36.000Z (about 2 years ago)
- Default Branch: develop
- Last Pushed: 2023-09-04T04:08:49.000Z (over 1 year ago)
- Last Synced: 2024-11-11T16:52:35.021Z (about 2 months ago)
- Topics: decorators, swagger, swagger-codegen, swagger-decorators, swagger-documentation, swagger-ui, swagger-ui-express, template
- Language: TypeScript
- Homepage:
- Size: 90.8 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Open Template Hub - Swagger Decorators v5[![Version](https://img.shields.io/npm/v/@open-template-hub/swagger-decorators?color=CB3837&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@open-template-hub/swagger-decorators)
[![Downloads](https://img.shields.io/npm/dt/@open-template-hub/swagger-decorators?color=CB3837&logo=npm&style=for-the-badge)](https://www.npmjs.com/package/@open-template-hub/swagger-decorators)
[![License](https://img.shields.io/github/license/open-template-hub/swagger-decorators?color=43b043&style=for-the-badge)](LICENSE)
[![Issues](https://img.shields.io/github/issues/open-template-hub/swagger-decorators?color=43b043&style=for-the-badge)](https://github.com/open-template-hub/swagger-decorators/issues)
[![PRCLosed](https://img.shields.io/github/issues-pr-closed-raw/open-template-hub/swagger-decorators?color=43b043&style=for-the-badge)](https://github.com/open-template-hub/swagger-decorators/pulls?q=is%3Apr+is%3Aclosed)
[![LastCommit](https://img.shields.io/github/last-commit/open-template-hub/swagger-decorators?color=43b043&style=for-the-badge)](https://github.com/open-template-hub/swagger-decorators/commits/master)
[![Release](https://img.shields.io/github/release/open-template-hub/swagger-decorators?include_prereleases&color=43b043&style=for-the-badge)](https://github.com/open-template-hub/swagger-decorators/releases)
[![SonarCloud](https://img.shields.io/sonar/quality_gate/open-template-hub_swagger-decorators?server=https%3A%2F%2Fsonarcloud.io&label=Sonar%20Cloud&style=for-the-badge&logo=sonarcloud)](https://sonarcloud.io/dashboard?id=open-template-hub_swagger-decorators)This library contains methods and decorators to ease and automate [Swagger](https://swagger.io) documentation.
## Topics
* [About the NPM Package](#about-the-npm-package)
* [Package Installation](#package-installation)
* [Using OTH Swagger Decorators](#using-oth-swagger-decorators)
* [@SwRoute](#swroute)
* [@SwTag](#swtag)
* [@SwSchema](#swschema)
* [@SwProp](#swprop)
* [@SwParam](#swparam)
* [@SwMethod](#swmethod)
* [Full Route Example Including All Method Types](#full-route-example-including-all-method-types)
* [Automation of Swagger Document Generation](#automation-of-swagger-document-generation)## About the NPM Package
### Package Installation
```sh
npm install --save @open-template-hub/swagger-decorators
```## Using OTH Swagger Decorators
### @SwRoute
This decorator helps you to define new route and can be specified on top of route class.
You must specify SwaggerRoute as the decorator argument.
```ts
import {
SwaggerRoute,
SwRoute,
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
@SwRoute( mySwaggerRoute )
export class MyRoute {
/// Route Methods
}
```### @SwTag
This decorator helps you to define new tag and can be specified on top of Route class.
You must specify SwaggerRoute as the decorator argument.
```ts
import {
SwaggerRoute,
SwaggerTag,
SwRoute,
SwTag,
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
const mySwaggerTag = {
name: 'MyTag',
route: mySwaggerRoute,
} as SwaggerTag;// Second tag under same route
const mySecondSwaggerTag = {
name: 'MySecondTag',
route: mySwaggerRoute,
} as SwaggerTag;@SwRoute( mySwaggerRoute )
@SwTag( mySwaggerTag )
@SwTag( mySecondSwaggerTag )
export class MyRoute {
/// Route Methods
}
```### @SwSchema
This decorator helps you to define new schema and can be specified on top of Schema class.
There are two types of Schema:
* Property Schema: Holds properties for Request Body and Response
* Parameter Schema: Holds parameters for Request Query and PathYou must specify SwaggerRoute as the first decorator argument for both Schema types.
The only difference for decoration, if you are defining a schema for parameters, you must set the second argument of
@SwSchema, which is isParameterSchema, to **true**.You can use Parameter Schema only with @SwParam parameters, and Property Schema can only be used with @SwProp properties.
Here you can see the example for Property Schema:
```ts
import {
SwaggerRoute,
SwSchema,
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
@SwSchema( mySwaggerRoute )
export class MySchema {
// Schema Properties
}
```Here you can see the example for Parameter Schema:
```ts
import {
SwaggerRoute,
SwSchema,
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
// Schema Parameters
}
```### @SwProp
This decorator helps you to define new property and can be specified on top of Properties.
This decorator takes two arguments. First argument is the description of the property and set the second argument, which is **required**, to **true** if the property is required. You do not need to set anything for the second argument if the property is not required.
Default values set to property will be used as example.
```ts
import {
SwaggerRoute,
SwSchema,
SwProp
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
@SwSchema( mySwaggerRoute )
export class MySchema {
@SwProp( 'The source application or service', true )
source: string = 'OTH Web UI';
@SwProp( 'Event creation time', true )
timestamp: number = 1666476669;
@SwProp( 'Can contain any kind of data payload' )
payload: any = { test: true };
}
```### @SwParam
This decorator helps you to define new parameter and can be specified on top of Parameters.
This decorator takes three arguments. First argument is the description of the parameter. Second argument specifies where this parameter will be stated, so it can be either PATH or QUERY and set the third argument, which is **required**, to **true** if the parameter is required. You do not need to set anything for the third argument if the parameter is not required.
Default values set to parameter will be used as example.
```ts
import {
SwaggerRoute,
SwSchema,
SwParam,
ParameterIn
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
@SwParam( 'Filter for reporter', ParameterIn.QUERY )
reporter: string = 'service-user';
@SwParam( 'Limit for records to return', ParameterIn.QUERY, true )
limit: number = 5;
}
```### @SwMethod
This decorator helps you to define new method and can be specified on top of route Methods.
This decorator takes only one argument which is SwaggerMethod.For better understanding, you can check all the properties for SwaggerMethod:
```ts
interface SwaggerMethod {
// Swagger Route
route: SwaggerRoute;// Method Name
name: string;// Method Summary
summary: string;// Method Description
description: string;// Http Method: GET, POST, PUT, PATCH, DELETE
httpMethod: HttpMethod;// Responses that method will return
responses: Array;// Identifies the security scheme
security?: SwaggerSecurityScheme;// Tags that method classified
tags?: Array;// Parameter schemas if you have in-query or in-path parameters
parameterSchemas?: Array;// Request Body
requestBody?: SwaggerRequestBody;
}
```**Related Interfaces**
* SwaggerRequestBody
```ts
interface SwaggerRequestBody {
// Request body content
content: SwaggerContent;// Is request body required
required: boolean;
}
```* SwaggerResponse
```ts
interface SwaggerResponse {
// Response code
responseCode: number;// Response description
description: string;// Response content
content: SwaggerContent;
}
```* SwaggerTag
```ts
interface SwaggerTag {
// Tag name
name: string;// Swagger Route
route: SwaggerRoute;
}
```* SwaggerContent
```ts
interface SwaggerContent {
// Related schema
schema: SwaggerSchema;// Is the content array of schema?
arrayOf?: boolean;
}
```### Full Route Example Including All Method Types
```ts
import {
HttpMethod,
ParameterIn,
SwaggerMethod,
SwaggerRequestBody,
SwaggerResponse,
SwaggerRoute,
SwaggerSchema,
SwaggerSecurityScheme,
SwaggerTag,
SwMethod,
SwParam,
SwProp,
SwRoute,
SwSchema,
SwTag,
} from '@open-template-hub/swagger-decorators';const mySwaggerRoute = { name: 'MyRoute' } as SwaggerRoute;
const mySwaggerTag = {
name: 'MyTag',
route: mySwaggerRoute,
} as SwaggerTag;@SwSchema( mySwaggerRoute )
export class MySchema {
@SwProp( 'The source application or service', true )
source: string = 'OTH Web UI';
@SwProp( 'Event creation time', true )
timestamp: number = 1666476669;
@SwProp( 'Can contain any kind of data payload' )
payload: any = { test: true };
}@SwSchema( mySwaggerRoute )
export class MyPatchSchema {
@SwProp( 'Can contain any kind of data payload' )
payload: any = { test: true };
}@SwSchema( mySwaggerRoute, true )
export class MyParameterSchema {
@SwParam( 'Filter for reporter', ParameterIn.QUERY )
reporter: string = 'service-user';
@SwParam( 'Limit for records to return', ParameterIn.QUERY, true )
limit: number = 5;
}@SwSchema( mySwaggerRoute, true )
export class MyDeleteSchema {
@SwParam( 'Identifier of the object that will be deleted', ParameterIn.QUERY )
id: string = '8034c607-a41d-4f29-8737-4cc9233a8b53';
}@SwRoute( mySwaggerRoute )
@SwTag( mySwaggerTag )
export class MyRoute {@SwMethod( {
httpMethod: HttpMethod.GET,
route: {
name: 'Sub-route name',
parent: mySwaggerRoute,
} as SwaggerRoute,
name: 'myGet',
summary: 'Summary of the method',
description: 'Description of the method',
security: SwaggerSecurityScheme.BEARER,
tags: [ mySwaggerTag ],
parameterSchemas: [ 'MyParameterSchema' ],
responses: [
{
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
arrayOf: true,
},
responseCode: 200,
description: 'OK',
} as SwaggerResponse,
],
} as SwaggerMethod )
myGet = () => {
// Route method
}@SwMethod( {
httpMethod: HttpMethod.POST,
route: {
name: 'Sub-route name',
parent: mySwaggerRoute,
} as SwaggerRoute,
name: 'myPost',
summary: 'Summary of the method',
description: 'Description of the method',
security: SwaggerSecurityScheme.BEARER,
tags: [ mySwaggerTag ],
requestBody: {
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
required: true,
} as SwaggerRequestBody,
responses: [
{
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
responseCode: 201,
description: 'Created',
} as SwaggerResponse,
],
} as SwaggerMethod )
myPost = () => {
// Route method
}@SwMethod( {
httpMethod: HttpMethod.PUT,
route: {
name: 'Sub-route name',
parent: mySwaggerRoute,
} as SwaggerRoute,
name: 'myPut',
summary: 'Summary of the method',
description: 'Description of the method',
security: SwaggerSecurityScheme.BEARER,
tags: [ mySwaggerTag ],
requestBody: {
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
required: true,
} as SwaggerRequestBody,
responses: [
{
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
responseCode: 200,
description: 'Updated',
} as SwaggerResponse,
],
} as SwaggerMethod )
myPut = () => {
// Route method
}@SwMethod( {
httpMethod: HttpMethod.PATCH,
route: {
name: 'Sub-route name',
parent: mySwaggerRoute,
} as SwaggerRoute,
name: 'myPatch',
summary: 'Summary of the method',
description: 'Description of the method',
security: SwaggerSecurityScheme.BEARER,
tags: [ mySwaggerTag ],
requestBody: {
content: {
schema: {
name: 'MyPatchSchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
required: true,
} as SwaggerRequestBody,
responses: [
{
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
responseCode: 200,
description: 'Updated',
} as SwaggerResponse,
],
} as SwaggerMethod )
myPatch = () => {
// Route method
}@SwMethod( {
httpMethod: HttpMethod.DELETE,
route: {
name: 'Sub-route name',
parent: mySwaggerRoute,
} as SwaggerRoute,
name: 'myDelete',
summary: 'Summary of the method',
description: 'Description of the method',
security: SwaggerSecurityScheme.BEARER,
tags: [ mySwaggerTag ],
parameterSchemas: [ 'MyDeleteSchema' ],
responses: [
{
content: {
schema: {
name: 'MySchema',
route: mySwaggerRoute,
} as SwaggerSchema,
},
responseCode: 200,
description: 'Updated',
} as SwaggerResponse,
],
} as SwaggerMethod )
myDelete = () => {
// Route method
}}
```## Automation of Swagger Document Generation
Add this codeblock to your index file, to the place after Routes are mounted where you are starting node application.
This codeblock will generate all Swagger Documents by reading decorators.
Change 'app' with the folder name where you want to keep and load Swagger Documents```ts
if ( process.env.OTH_SWAGGER_ON_GENERATION === 'true' ) {
SwaggerDocumentation.getInstance().generateDocument(
Path.join( __dirname, 'app' )
);process.exit( 1 );
}
```Add "swagger" command to package.json scripts
```
"scripts": {
...
"swagger": "OTH_SWAGGER_ON_GENERATION=true npm start"
}
```You can use "swagger-ui-express" package to load Swagger UI from the generated "index.swagger" document spec.
```
npm i swagger-ui-express
``````ts
if (
process.env.OTH_SWAGGER_ON_GENERATION !== 'true'
) {
const { SwaggerSpec } = require( './app/swagger/index.swagger' );
const swaggerUi = require( 'swagger-ui-express' );
const swaggerSpecification = new SwaggerSpec();
app.use(
'/docs',
swaggerUi.serve,
swaggerUi.setup( swaggerSpecification.getSpec() )
);
}
```And when your decorators are stated in your code and ready, you can run and automate simply the "swagger" command:
```
npm run swagger
```# Sponsors
No sponsors yet! **Will you be the first?**
## Contributors
Furkan Yavuz
π¬ π π
Fatih Turker
π¬ π π
Mert Sarac
π¬ π π
JΓ©rΓ΄me Poskin
π¬ π π
## Contributing
Refer to **[CONTRIBUTING.md](https://github.com/open-template-hub/.github/blob/master/docs/CONTRIBUTING.md)** to see how to contribute to Open Template Hub.
## Code of Conduct
Refer to **[CODE_OF_CONDUCT.md](https://github.com/open-template-hub/.github/blob/master/docs/CODE_OF_CONDUCT.md)** to see contributor covenant code of conduct.
## LICENSE
The source code for this project is released under the [MIT License](LICENSE).