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

One spec to rule them all

paul souche
November 12, 2019

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.

paul souche

November 12, 2019
Tweet

More Decks by paul souche

Other Decks in Programming

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