cdk-apig-utility
Have you ever wished that Swagger could be automatically generated from JSDoc?
It auto-generates useful CDK’s objects from TypeScript entity(and its JSDoc) to define swagger easily at API Gateway.
Requirement
- @aws-cdk/aws-apigateway@1.27.0
- typescript
Install
$ npm install cdk-apig-utility
Usage
At first, please understand the following CDK's document.
Following is the example of CDK.
// We define the JSON Schema for the transformed valid response;
Perhaps you were in pain when you had to write the same contents of the entity in the generation of models and request parameters.
Moreover, you must create the CfnDocumentationPart object so as to write the description of request parameters.
You can auto-generate the above objects from following examples.
Model
Example
Model can be generated from entity objects.
import {SubIf} from './sub/sub-if'; export interface SampleIf { /** * @desc JSDoc of param1 */ param1: string; /** * @description JSDoc of param2 */ param2: number; /** * ignored comment of param3 */ param3: boolean; param4: string[]; param5: number[]; param6: boolean[]; param7: SubIf; param8: SubIf[];}
export interface SubIf { subParam1: string;}
Execution
;; // You can also use getModelsFromDir method.; // You can search the model what you want by 'modelName'(It has a class name or interface name). ;
Result
If you have written the JSDoc's @desc
or @description
tag at the property, it can be converted to description.
Request parameters
Example
Request parameters can be generated from method's arguments.
/** * This is sample method. * * @param limit * @param sort 1:ascending 2:descending * @param word some word * @param isSomeFlg some boolean value1¬ * @param someArray some array */ async getSomething1(limit: number, offset: number, sort: number, word?: string, isSomeFlg?: boolean, someArray?: string[]): Promise<any> { }
Execution
;
Result
The values(true or false) can be generated from '?' of arguments.
Request parameter's documents
Request parameters' documents can be generated from method's arguments and JSDoc.
/** * This is sample method. * * @param limit * @param sort 1:ascending 2:descending * @param word some word * @param isSomeFlg some boolean value1¬ * @param someArray some array */ async getSomething1(limit: number, offset: number, sort: number, word?: string, isSomeFlg?: boolean, someArray?: string[]): Promise<any> { }
Execution
;
Result
If you have written the JSDoc's @param
tag at the method, it can be converted to description.
You can use this result when you create the CfnDocumentationPart.
How to use with CDK.
Please see the following test code.
You can use this model at both request and response.