Upgrade to Pro — share decks privately, control downloads, hide ads and more …

NestJS アプリケーションから Swagger を自動生成する / nestjs-meetup-tokyo-01

euxn23
November 29, 2019

NestJS アプリケーションから Swagger を自動生成する / nestjs-meetup-tokyo-01

euxn23

November 29, 2019
Tweet

More Decks by euxn23

Other Decks in Programming

Transcript

  1. Who? Yuta Suzuki (@euxn23) Engineer @ Japan Digital Design, Inc

    すき: ドリュウズ きらい: ウオノラゴン
  2. Controller @Controller() export class AppController { constructor(private readonly appService: AppService)

    {} @Get('/users') @ApiResponse({ status: HttpStatus.OK, type: GetUsersResponse }) async getUsers( @Query() { userIds }: GetUsersRequest, ): Promise<GetUsersResponse> { const users = await this.appService.getUsers(userIds); return { users }; } } @ApiResponse() で定義したステータスが swagger に吐かせる @Query() (POST の場合は @Body()) で定義した param が sagger に吐かれる docs.nestjs.com/controllers#request-object
  3. DTO export abstract class GetUsersRequest { @ApiModelProperty({ example: ['10', '11']

    }) userIds?: string | string[]; } export abstract class GetUsersResponse { @ApiModelProperty({ example: usersStub }) users!: IUser[]; } @ApiModelProperty() でパラメータの詳細を定義する ここで example を設定しておくと、後述する stub の値になる
  4. Swagger Entry export async function createSwaggerApp(): Promise<INestApplication> { const app

    = await NestFactory.create(AppModule); const options = new DocumentBuilder().build(); const document = SwaggerModule.createDocument(app, options); SwaggerModule.setup('api', app, document); return app; } export async function bootstrap(): Promise<void> { const app = await createSwaggerApp(); await app.listen(8081); } bootstrap(); /api でドキュメントページへ /api-json で swaggewr json 吐き出し
  5. swagger(v2) から openapi(v3) への変換 $ swagger2openapi http://localhost:8081/api-json >| src/swagger/swagger.json NestJS

    の吐き出す swagger は v2 である 容易に stub 化するために使用したい apisprout は openapi(v3) のみ対応 swagger を openapi に変換してファイルに出力しておくとドキュメントにもなるので便利
  6. stub の起動 $ docker run -p 8082:8000 -v $PWD/src/swagger/swagger.json:/api.json danielgtaylor/apisprout

    /api.json apisprout の docker を使って stub 化 CI 等でも簡単に stub 化できる gulp 等をうまく使うことで、 test のフローにうまく組み込むことも可能