@hublo/swagger-typescript-types
v3.5.2
Published
Generating typescript artifacts from a remote swagger json
Downloads
3,462
Maintainers
Keywords
Readme
swagger-typescript-types
Generating typescript types from swagger.
⚡ Purpose
Here is a little utility to generate typescript artifacts from swagger. This can be useful when you want to sync types between your backend and your frontend.
For example, we have this backend exposing a swagger. The /devs/by-squads
route returns an array of DevDto
which is a model described in swagger.
Now, I could just write the interface for it myself in the frontend codebase 🤔, right? This is simple enough in our example:
export interface DevDto {
id: number;
idSquad: number;
firstName: string;
avatar: string;
}
But what if we could just extract these models and generate types instead? Oh...! 😏
🔶 Disclaimer
🚨 I wrote this for a stack based on nestjs for the backend and react-query for the frontend, so this tool may or may not suit your needs. If you think about another usecase, do not hesitate to drop an issue 🙃.
⚡ Installation
To install, use either yarn or npm:
yarn add -D swagger-typescript-types
npm i -D swagger-typescript-types
⚡ Typical use : cli
🔶 From an url
Let's say we have a backend exposing endpoints on this url: https://devfriends-backend.fly.dev. Now, swagger exposes a json file on the /-json path in this example.
Knowing this, we can add a script to our package.json:
{
"scripts": {
"api:sync": "generateTypesFromUrl -u https://devfriends-backend.fly.dev/-json -o ./src/api/types [-t]"
}
}
The generateTypesFromUrl
task takes two arguments:
| name | description | Example | | ---- | --------------------------------------------------- | ------------------------------------------ | | u | The url of the json exposed by the targeted swagger | https://devfriends-backend.fly.dev/-json | | o | Where to write our exposed types | ./src/api/types |
Optionally, you can use -t
flag if you're using importsNotUsedAsValues
in your tsconfig compiler options. It will generate imports like so:
import type { ... } from ...
Our task will do a few things using these arguments when called:
✔️ Fetch the json exposed by our swagger (exposed in our example at the `-json` path).
✔️ Validate the json retrieved against [openapiv3 schema](https://github.com/APIDevTools/openapi-schemas).
✔️ Extract models and generate typings from them.
✔️ Write them on the path defined as second argument (./src/api/types/api-types.ts).
✔️ For each route, create a file containing the endpoint path and re-exporting parameters / request body / responses types.
✔️ Warn us if some specs are missing (missing response types, missing path parameters, etc.).
🔶 From a file
We can also generate types from a file:
{
"scripts": {
"api:sync": "generateTypesFromFile -i ./specs/swagger.json -o ./src/api/types [-t]"
}
}
The generateTypesFromUrl
task takes two arguments:
| name | description | Example | | ---- | --------------------------------- | -------------------- | | i | The path of the swagger json file | ./specs/swagger.json | | o | Where to write our exposed types | ./src/api/types |
Optionally, you can use -t
flag if you're using importsNotUsedAsValues
in your tsconfig compiler options. It will generate imports like so:
import type { ... } from ...
Again, our task will do the following:
✔️ Read the json file.
✔️ Validate it against [openapiv3 schema](https://github.com/APIDevTools/openapi-schemas).
✔️ Extract models and generate typings from it.
✔️ Write them on the path defined as second argument (./api-types.ts).
✔️ For each route, create a file containing the endpoint path and re-exporting parameters / request body / responses types.
✔️ Warn us if some specs are missing (missing response types, missing path parameters, etc.).
⚡ Generated files
Taking our example backend, let's check the files generated:
./api-types.ts
export interface SquadDto {
id: number;
name: string;
}
export interface AllSquadsResultDto {
result: Array<SquadDto>;
}
export interface ApiResponseDto {
statusCode: number;
message: string;
}
export interface DevDto {
id: number;
idSquad: number;
firstName: string;
avatar: string;
}
export interface SquadsDevelopersResultDto {
result: Array<DevDto>;
}
export interface BadRequestDto {
statusCode: number;
message: string | Array<string>;
error: string;
}
export interface AllDevsResultDto {
result: Array<DevDto>;
}
export interface ChangeSquadBodyDto {
idDev: number;
idSquad: number;
}
export interface ChangeSquadResultDto {
result: string;
}
export interface DevelopersBySquadsBodyDto {
idSquads: Array<number>;
}
export interface DevelopersBySquadsResultDto {
result: Array<DevDto>;
}
Now let's check an endpoint:
./SquadsController/getSquadsDevelopers.ts
/*
* method: get
* summary: Get the developers belonging to a squad
* description: Retrieves the squad developers
*/
import { SquadsDevelopersResultDto, BadRequestDto, ApiResponseDto } from './../api-types';
export const getPath = (id: number): string => `/squads/${id}/devs`;
export type GetSquadsDevelopersSuccess = SquadsDevelopersResultDto;
export type GetSquadsDevelopersError = BadRequestDto | ApiResponseDto;
⚡ Api
On top of the cli, this package exposes the following functions:
🔶 Functions
🌀 generateTypesFromUrl
This function generates types from a swagger exposed online. Typical use:
const params = {
swaggerJsonUrl: 'https://devfriends-backend.fly.dev/-json',
outputPath './src/specs',
importsNotUsedAsValues: false
};
const {
typesGenerated, // boolean, specifies whether types have been extracted (./api-types.ts file)
endpointsCount // number of endpoints extracted
}: GenerationResult = await generateTypesFromUrl(params);
🌀 generateTypesFromFile
This function generates types from a swagger json file. Typical use:
const params = {
inputPath: './src/api/swagger.json',
outputPath './src/specs',
importsNotUsedAsValues: false
};
const {
typesGenerated, // boolean, specifies whether types have been extracted (./api-types.ts file)
endpointsCount // number of endpoints extracted
}: GenerationResult = await generateTypesFromFile(params);
🌀 validateSchema
This function validates some arbitrary json against the openapiv3 schema. Typically use:
const json: InputSwaggerJson = { ... };
const schema: ValidatedOpenaApiSchema = await validateSchema(data);
🌀 generateTypesDefinitions
This function extracts models from the swagger json and generates typings from them. Typical use:
const outPath = './src/api/types';
const schema: ValidatedOpenaApiSchema = { ... };
const importsNotUsedAsValues = true
await generateTypesDefinitions(outPath, schema, importsNotUsedAsValues);