One spec to rule them all

Slide 1

Slide 1 text

One spec to rule them all An openapi journey Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment

Slide 2

Slide 2 text

Me myself and I @paul.souche paulsouche @paulsouche 2 Paul SOUCHE Meetup nestjs 11/12/2019 https://github.com/paulsouche/open-api-nest-experiment

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

11 Tools ( 1 / 5) cli spec validation ● swagger-cli Standard but “cli only” => must provide a ﬁle (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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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