Hi! I'd like to share some code that helped me a lot to work with an API that had been changed often.
Idea
The idea is to generate TypeScript types from Swagger's definition. I found an awesome npm library called @codegena/oapi3ts-cli. To use this you need to store JSON file with API schema locally.
Let's move to code...
Install dependencies
I used axios to fetch data. You can use anything you want.
npm i -D @codegena/oapi3ts-cli axios
Create folders and files that we need
Now let's create the scripts/ folder in the root of your project and add two files (fetch-schema.js and schema-codegen.js) inside of the created folder. Also, we need to create src/typings/ folder where we're gonna save our types and API schema.
// scripts/schema-codegen.js
const cliLib = require('@codegena/oapi3ts-cli');
const cliApp = new cliLib.CliApplication();
cliApp.cliConfig.typingsDirectory = '';
cliApp.createTypings();
// scripts/fetch-schema.js
const axios = require('axios');
const https = require('https');
const fs = require('fs');
const path = require('path');
const instance = axios.create({
httpsAgent: new https.Agent({
rejectUnauthorized: false,
}),
});
/* The code below will create operation names.
Instead of `/api/User/GetList` you'll get `UserGetList` type
that you can use anywhere */
function addOperationIdsToSchema(schema) {
const data = schema;
Object.keys(data.paths).forEach((endpointPath) => {
const operations = Object.keys(data.paths[endpointPath]);
operations.forEach((operation) => {
const oprationName = endpointPath.replace('/api/', '').replace(/\//g, '');
data.paths[endpointPath][operation].operationId = oprationName;
});
});
return data;
}
instance
.get('https://YOUR_ENDPOINT_TO_SWAGGER/swagger.json')
.then((response) => {
const updatedSchema = addOperationIdsToSchema(response.data);
fs.writeFileSync(
path.resolve(__dirname, '../src/typings/api-schema.json'),
JSON.stringify(updatedSchema, null, 2),
);
console.log('==> Schema fetched successfully...');
})
.catch(console.error);
Update package.json
And one of the last things you need to do is add to package.json these lines:
{
...
"scripts": {
...
"schema:fetch": "node ./scripts/fetch-schema.js",
"schema:generate": "node ./scripts/schema-codegen.js --srcPath ./src/typings/api-schema.json --destPath ./src/typings/api --separatedFiles false",
"schema:codegen": "npm run schema:fetch && npm run schema:generate:api"
}
}
Now you can generate your API schema with this command:
npm run schema:codegen
This command generated src/typings/api/ folder with TypeScript definitions.
If you got into some problems, please, let me know to be able to update the article for future readers.
Top comments (4)
this is a bit weird. You explicitly include cli in the name but I only see examples of using it programmatically? Did I misunderstand or overlook something? :-)
Otherwise seem cool.
en.wikipedia.org/wiki/Command-line...
I agree that it seems to be weird but I haven't found anything else in docs of that package.
Nice, and I’ll give it a try, but … you might want to correct the first line of those example files, for they are not json but js …
Oh, yeah! I'll fix that. Thank you so much