openapi-ts-sdk-builder
v8.0.1
Published
Create a TypeScript SDK from an OpenAPI 3 definition
Downloads
208
Maintainers
Readme
openapi-ts-sdk-builder
Create a TypeScript SDK from an OpenAPI 3 definition
A TypeScript rewrite of openapi-js-sdk-builder.
It basically brings a minimal TypeScript SDK from an OpenAPI3 file with no OOP inside. It works with any HTTP client.
Usage
With a raw Node script:
import { generateSDKFromOpenAPI } from 'openapi-ts-sdk-builder';
import { readFileSync, writeFileSync } from 'fs';
const openAPIContents = readFileSync('openapi.json', 'utf-8');
const sdkContents = generateSDKFromOpenAPI(
openAPIContents,
{
sdkVersion: 'v1.1.1',
ignoredParametersNames: ['cookie', 'X-API-Version', 'X-SDK-Version'],
undocumentedParametersNames: ['X-Application-Version'],
},
{
generateUnusedSchemas: true,
brandedTypes: [
'SensorUUID',
'UUID',
'Locale',
'TimeZone',
'ValueName',
'SensorVariable',
],
generateRealEnums: true,
exportNamespaces: true,
},
);
writeFileSync('src/sdk.ts', sdkContents, 'utf-8');
Sample usage with axios
:
import BaseAPI, { APIStatuses } from './sdk.ts';
import axios from 'axios';
import querystring from 'querystring';
import type { RequestExecutor } from './sdk.ts';
import type { AxiosRequestConfig } from 'axios';
const executeRequest: RequestExecutor<AxiosRequestConfig> = async (
httpRequest,
operationId,
options,
) => {
const callOptions = {
...options,
baseURL: 'http://localhost:3000',
url: httpRequest.path,
method: httpRequest.method,
headers: {
...(options.headers || {}),
...(httpRequest.headers || {}),
},
params: httpRequest.params,
data: httpRequest.body,
paramsSerializer: querystring.stringify.bind(querystring),
validateStatus: (status: number) =>
APIStatuses[operationId].includes(status),
};
const response = await axios(callOptions);
return {
status: response.status,
headers: response.headers,
body: response.data,
};
};
// Use the API
await BaseAPI.getPing(executeRequest);
await BaseAPI.getUser(executeRequest, { userId: '123' });
// Generate URIs only use the API then
await APIURIBuilders.buildGetPingURI({
/*...*/
});
// To know which method is used by an endpoint
APIMethods.getPing; // => get
// To know which status codes can be returned by an endpoint
APIStatuses.getPing; // => ["default", 200]
// Generate a complete endpoint input
// (may be useful when you want to pass
// HTTP requests to another process )
APIInputBuilders.buildGetPingInput({
/*...*/
});
You can also safely operate on the API by doing so:
import BaseAPI, { APIStatuses } from './sdk.ts';
import config from './config';
import YError from 'yerror';
import type { RequestExecutor, Components } from './sdk.ts';
import type { AxiosRequestConfig } from 'axios';
export { Enums };
export type { Components };
type AuthTokenInput = { token?: string };
const API = Object.keys(BaseAPI).reduce((FinalAPI, operationId) => {
FinalAPI[operationId] = async (
{ token, ...input }: unknown & AuthTokenInput,
options: AxiosRequestConfig = {},
) => {
try {
const response = await BaseAPI[operationId](
executeRequest,
{
...input,
xApplicationVersion: config.applicationVersion,
},
{
...options,
baseURL: config.apiURL,
headers: {
...options.headers,
...(token
? {
authorization: `Bearer ${token}`,
}
: {}),
},
},
);
return response;
} catch (err) {
console.error('Got an API error:', err.stack);
throw new YError(
err.response?.data?.error ? 'E_API_ERROR' : 'E_UNEXPECTED_ERROR',
err.response?.data,
);
}
};
return FinalAPI;
}, {}) as {
[P in keyof typeof BaseAPI]: (
input: Parameters<typeof BaseAPI[P]>[1] & AuthTokenInput,
config?: AxiosRequestConfig,
) => Promise<ReturnType<typeof BaseAPI[P]>>;
};
export default API;
Finally, you may appreciate using it with the
useSSR
React hook to benefit from your SDK
types:
import useSWR from 'swr';
import API from './api';
type Handler<I, O> = (input: I) => Promise<O>;
type HandlerInput<T> = T extends Handler<infer I, unknown> ? I : never;
type HandlerOutput<T> = T extends Handler<unknown, infer I> ? I : never;
const API_KEYS: Record<any, string> = Object.keys(API).reduce((hash, key) => {
hash[API[key]] = key;
return hash;
}, {});
export default function useAPISWR<T extends Handler<any, any>>(
swrCouple: [T, HandlerInput<T>],
options?: Parameters<typeof useSWR>[2],
) {
const uniqueKey = swrCouple
? Object.keys(swrCouple[1]).reduce(
(finalKey, key) => finalKey + key + JSON.stringify(swrCouple[1][key]),
// Sadly, here, we cannot rely on `swrCouple[0].name` to
// build the unicity key since the build destroys it
API_KEYS[swrCouple[0]] + '-',
)
: null;
return useSWR<
Awaited<HandlerOutput<T>> extends { body: infer D } ? D : never
>(
uniqueKey,
async () => (await swrCouple[0](swrCouple[1])).body,
options as any,
);
}
API
openapi-ts-sdk-builder
openapi-ts-sdk-builder~generateSDKFromOpenAPI(openAPIContent, options, [typeOptions]) ⇒ Promise.<string>
Build a JS SDK from an OpenAPI file
Kind: inner method of openapi-ts-sdk-builder
Returns: Promise.<string> - The SDK JS code
| Param | Type | Description | | --- | --- | --- | | openAPIContent | string | | | options | Object | | | options.sdkVersion | string | The SDK version | | [options.sdkName] | string | The SDK name (default to API) | | [options.ignoredParametersNames] | Array.<string> | Provide a list of parameters to ignore | | [options.undocumentedParametersNames] | Array.<string> | Provide a list of parameters to keep undocumented | | [typeOptions] | Object | Options to be passed to the type generator |