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
   

   View Slide

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
   

   View Slide

3. Summary
   ● @nestjs/swagger
   ● Tools
   ● Demo
   ● Limitations & Conclusion
   3
   Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
   

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

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

   View Slide

10. 10
    Tools
    Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

16. 16
    Demo
    Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
    

    View Slide

17. 17
    Limitations &
    Conclusion
    Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
    

    View Slide

18. 18
    Limitations & Conclusion ( 1 / 2)
    null
    Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
    

    View Slide

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
    

    View Slide

20. 20
    Thank you
    Questions ?
    Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment
    

    View Slide

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
    

    View Slide