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. 5 @nestjs/swagger ( 1 / 5) Paul SOUCHE Meetup nestjs

    11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  5. 6 @nestjs/swagger ( 2 / 5) Paul SOUCHE Meetup nestjs

    11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  6. 7 @nestjs/swagger ( 3 / 5) Paul SOUCHE Meetup nestjs

    11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  7. 8 @nestjs/swagger ( 4 / 5) Paul SOUCHE Meetup nestjs

    11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  8. 9 @nestjs/swagger ( 4 / 5) Paul SOUCHE Meetup nestjs

    11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 18 Limitations & Conclusion ( 1 / 2) null Paul

    SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
  15. 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
  16. 20 Thank you Questions ? Paul SOUCHE Meetup nestjs 11/12/2019

    https://github.com/paulsouche/open-api-nest-experiment
  17. 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