OpenAPI client generator. Creates at runtime a fully functional api client based on an OpenAPI Specification. Providing automatic methods creation parameters definitions and validations.
OpenAPI client generator. Creates, at runtime, a fully functional api client based on an OpenAPI Specification v3. Providing automatic methods creation parameters definitions and validations. The goal is to provide consistency and a fast way to create and maintain api clients. It reduces the need of writing and preparing by hand all the necessary code to handle the communication with such servers.
npm install oas-client --no-optional
--no-optional because ajv (to validate body schema) and yamljs (to read the spec from .yml format) are optional.
const specExample = {
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
},
"servers": [
{
"url": "https://github.com"
}
],
"paths": {
"/{profile}": {
"get": {
"operationId": "fetchProfile",
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile to retrieve",
"schema": {
"type": "string"
}
}
]
}
},
"/{profile}/{repository}": {
"get": {
"operationId": "fetchRepository"
},
"parameters": [
{
"name": "profile",
"in": "path",
"required": true,
"description": "The profile to retrieve",
"schema": {
"type": "string"
}
},
{
"name": "repository",
"in": "path",
"required": true,
"description": "The repository to retrieve",
"schema": {
"type": "string"
}
}
]
}
}
};
const githubClient = oasClient.create(specExample);
// http://github.com/DiegZoracKy will be requested
githubClient.fetchProfile({data: {profile: 'DiegoZoracKy'}})
.then(console.log)
.catch(console.error);
// http://github.com/DiegZoracKy/oas-client will be requested
githubClient.fetchRepository({data: {profile: 'DiegoZoracKy', repository: 'oas-client'}})
.then(console.log)
.catch(console.error);
All the paths and operations (http methods) presented on the specification becomes a method accessible by their operationId (when present) or by its pathOperation (e.g. "GET /path") on the client object generated. When passing data for a method, the specification is what tells the client what to do with it. If it should be set as a querystring, as a path templating, etc.
On the following example:
githubClient.fetchProfile({data: {profile: 'DiegoZoracKy'}})
The request GET https://github.com/DiegoZoracky will be issued, as the specification tells that fetchProfile is the operationId related to the path /{profile} when being called via GET. Also it is defined that the parameter profile is present on the path. Finally enters the information contained at servers, which instructs to where the request should be made.
The same operation can be called by its pathOperation (essential to when there is not an operationId defined):
githubClient['GET /{profile}']({data: {profile: 'DiegoZoracKy'}})
The create method accepts a second parameter with a config object:
oasClient.create(specification, options);
In order to validate the post body following the schema defined at the property requestBody, set:
validateBody: true
.
Install de optionalDependency ajv to enable this feature.
By default the client will validate the parameters defined as required on the specification. When they are not passed in, an error will be returned and the request will not be performed. To turn off this validation set:
validateParameters: false
.
Default parameters can be set at once to all requests to be made (useful to set Authorization tokens):
{
defaultParameters: {
cookie: { Authorization: 'Token!' },
}
}
or by specific paths.
{
paths: {
'GET /search': {
defaultParameters: {
query: {
limit: '20'
}
}
}
}
}