OpenAPI Spec HTTP Client
Feed it a JSON Spec, it will spit out a lightweight HTTP client!
Why
While there are plenty of "code generators" for OpenAPI Specification, they create a lot of "garbage" code that you may not need, and there while there are others that follow a similar path of this library, they still attempt to do too much! (like request validation before sending)
This library does not concern itself with anything other than constructing an HTTP request and sending it!
FAQ
-
Why no validation?
You should rely on validation & sanitation at the source of truth: The API server itself! -
YAML Support?
This package does not natively support OpenAPI Specification YAML format, but you can easily convert to JSON before callingoas-rqeuest
Example
usingYAML
const YAML = require('yaml') const { readFile } = require('fs/promises') const file = await readFile('openapi.yml', 'utf8') const spec = YAML.parse(file) const OASRequest = require('oas-request')(spec)
usingapidevtools/swagger-cli
npx apidevtools/swagger-cli bundle spec/openapi.yml --outfile spec.json
What
Some feature highlights:
- Automatic methods creation
- Path Templating
- uses
cross-fetch
for all HTTP operations
Usage
e.g. petstore.json
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore"
},
"servers": [
{
"url": "http://petstore.swagger.io/{version}",
"variables": {
"version": {
"description": "api version",
"default": "v1"
}
}
}
],
"paths": {
"/pets": {
"get": {
"operationId": "listPets",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A paged array of pets",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
}
},
"post": {
"operationId": "createPets",
"responses": {
"201": {
"description": "Null response"
}
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "showPetById",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Pet": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
}
const spec = require('./petstore.json')
const OASRequest = require('oas-request')(spec)
// define root server url
const request = new OASRequest({
server: 'http://petstore.swagger.io/v1'
})
// or use one from the OpenAPI Specification
const request = new OASRequest({
server: {
url: spec.servers[0].url
// populate values for server (see OpenAPI Specification #4.7.5)
variables: {
version: 'v2'
}
}
})
// auto generated methods match OpenAPI Specification "operationId"
await request.listPets()
await request.createPets()
await request.showPetById()
Advanced Usage
const spec = require('./petstore.json')
const OASRequest = require('oas-request')(spec)
// always use JSON headers
const request = new OASRequest({
server: 'http://petstore.swagger.io/v1'
headers: {
'accept': 'application/json',
'content-type': 'application/json'
}
})
// POST with JSON
const body = JSON.stringify(body)
const response = await request.createPets({ body })
const data = await response.json()
console.log(data)
new OASRequest(APIOptions)
Construct a new instance of the API request, returns an Object with auto generated method names matching each of the unique OpenAPI Specification operationId
Example
spec.json
{
...
"paths": {
"/pets": {
"get": {
"operationId": "listPets",
...
},
"post": {
"operationId": "createPets",
...
}
},
"/pets/{petId}": {
"get": {
"operationId": "showPetById",
...
}
}
}
}
app.js
const spec = require('./petstore.json')
const OASRequest = require('oas-request')(spec)
// define root server url
const request = new OASRequest({ server: 'http://petstore.swagger.io/v1' })
// auto generated methods match OpenAPI Specification "operationId"
await request.listPets()
await request.createPets()
await request.showPetById()
APIOptions
property | type | required | default | description |
---|---|---|---|---|
client |
Function |
✗ | unfetch |
a Function that executes the HTTP request. (see clientFunction )
|
server |
String|Object |
✗ | spec.servers[0] |
Root server url String, or Server Object
|
headers |
Object |
✗ | {} |
Global HTTP request headers (used with every request) |
query |
Object |
✗ | {} |
Global Query String (used with every request) |
params |
Object |
✗ | {} |
Global Path Templating parameters (used with every request) |
clientFunction
a Function
with the signature: Function(url, requestOptions)
to execute the HTTP request, the default built-in function uses cross-fetch
, you can customize the client to use whatever HTTP library you prefer.
⚠️ Note:
url
is an instance ofURL
options.query
will be processed to construct theurl
, then deleted.options.params
will be processed and used in Path Templating, then deleted.
Example: always assume JSON
const spec = require('./petstore.json')
const fetch = require('cross-fetch')
const OASRequest = require('oas-request')(spec)
const request = new OASRequest({
client: async function (url, options) {
const response = await fetch(url, {
...options,
// always set body to JSON
body: JSON.stringify(options.body),
headers: {
...options.headers,
// always set headers to JSON
...{
'accept': 'application/json',
'content-type': 'application/json'
}
}
})
// always parse body as JSON
response.data = await response.json()
return response
}
})
const response = await request.createPet({
body {
id: 1,
name: 'Ruby'
}
})
console.log(response.data)
Example: using axios
const spec = require('./petstore.json')
const axios = require('axios')
const OASRequest = require('oas-request')(spec)
const request = new OASRequest({
client: async function (URL, options) {
return axios({
...options,
maxRedirects: 10,
url: URL.toString(),
httpsAgent: new https.Agent({ keepAlive: true })
})
}
})
const response = await request.createPet({
data: {
id: 1,
name: 'Ruby'
},
timeout: 1000
})
ServerObject
⚠️ Note: This is not the same as OpenAPI Specification's Server Object, though it's similarly structured
property | type | required | description |
---|---|---|---|
url |
String |
✓ | Root server url |
variables |
Object |
✗ | Key-value pairs for server URL template substitution |
__Operation__(requestOptions)
- Operation method names are generated from the unique OpenAPI Specification
operationId
- Operations method will return with a call to the specified
Client Function
requestOptions
The requestOptions
Objects maps to Fetch init
parameter with some special considerations:
-
method
will always be set based on the OpenAPI Specification method for this operation -
query
is a special property used to construct the final URL -
params
is a special property used to construct the final URL Path (Path Templating)
Full Example
const spec = require('./petstore.json')
const API = require('oas-request')(spec)
// send to httpbin so we can inspect the result
const request = new OASRequest({
server: 'http://petstore.swagger.io/v1',
headers: {
'user-agent': 'my-awsome-api-client',
'x-special-header': 'sent-with-every-request'
}
})
await request.listPets({
query: {
limit: 100
}
})
await request.getPetById({
params: { petId: 'my-pet' }
headers: {
'x-additional-header': 'this operation needs this'
}
})
await request.updatePetById({
params: { petId: 'my-pet' },
body: {
name: "ruby",
isGoodDog: true
}
})
Author: Ahmad Nassri • Twitter: @AhmadNassri