One spec to rule them all

Some people have already a swagger to manage their api documentation but do you know what kind of tools are available around the open api specification ? In this talk we will briefly describe tools and methods in nestjs.

Transcript

1. One spec to rule them all An openapi journey Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
2. Me myself and I @paul.souche paulsouche @paulsouche 2 Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
3. Summary • @nestjs/swagger • Tools • Demo • Limitations & Conclusion 3 Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
4. 4 @nestjs/swagger Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
5. 5 @nestjs/swagger ( 1 / 5) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
6. 6 @nestjs/swagger ( 2 / 5) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
7. 7 @nestjs/swagger ( 3 / 5) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
8. 8 @nestjs/swagger ( 4 / 5) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
9. 9 @nestjs/swagger ( 4 / 5) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
10. 10 Tools Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
11. 11 Tools ( 1 / 5) cli spec validation • swagger-cli Standard but “cli only” => must provide a file (no url ) • openapi-schema-validator Export directly OpenAPISchemaValidator class to validate json object Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
12. 12 Tools ( 2 / 5) swagger.json generation • openapi3-ts Script your swagger.json Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
13. 13 Tools ( 3 / 5) DTO only generation • openapi-to-ts Not in typescript / no namespace • sw2dts TypeScript + namespace / dto only • dtsgenerator TypeScript + namespace / dto + parameters Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
14. 14 Tools ( 4 / 5) Don’t use • oapi3codegen • @api-platform/client-generator Not usable in production (version) just don’t work aims too far creating a whole app Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
15. 15 Tools ( 5 / 5) Client generator • @openapitools/openapi-generator-cli Standard openapi generator npm wrapper Requires java Lot of clients & servers (axios, fetch, java, ruby, python...) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
16. 16 Demo Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
17. 17 Limitations & Conclusion Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
18. 18 Limitations & Conclusion ( 1 / 2) null Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
19. 19 Limitations & Conclusion ( 2 / 2) • Literal types (enum hack) • Nominal types (fallback to string) • Conditional types on parameters (can generate an union type) • ... Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
20. 20 Thank you Questions ? Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
21. 21 Ressources • repository (https://github.com/paulsouche/open-api-nest-experiment) • openapi generator (https://openapi-generator.tech/) • nestjs openapi docs (https://docs.nestjs.com/recipes/swagger) • @openapitools/openapi-generator-cli (https://www.npmjs.com/package/@openapitools/openapi-generator-cli) • sw2dts (https://www.npmjs.com/package/sw2dts) • openapi-to-typescript (https://www.npmjs.com/package/openapi-to-typescript) • dtsgenerator (https://www.npmjs.com/package/dtsgenerator) Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment