package
Feed it a JSON Spec, it will spit out a lightweight HTTP client!
npm install oas-requestGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 6 packages.
283.3 kB
Includes dependencies.
Feed it a JSON Spec, it will spit out a lightweight HTTP client!
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!
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 calling oas-rqeuest
YAMLconst YAML = require('yaml')
const { readFile } = require('fs/promises')
const file = await readFile('openapi.yml', 'utf8')
const spec = YAML.parse(file)
Some feature highlights:
cross-fetch for all HTTP operationspetstore.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"
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
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
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
spec.json{
...
"paths": {
"/pets": {
"get": {
"operationId": "listPets",
...
},
"post": {
"operationId": "createPets",
...
}
},
"/pets/{petId}": {
"get": {
"operationId": "showPetById",
...
}
}
}
}app.jsconst spec =
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 | ✗ |
clientFunctiona 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:
urlis an instance ofURLoptions.querywill be processed to construct theurl, then deleted.options.paramswill be processed and used in Path Templating, then deleted.
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
...{
axiosconst 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 })
})
}
})
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)apidevtools/swagger-clinpx apidevtools/swagger-cli bundle spec/openapi.yml --outfile spec.json{} |
| 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) |
operationIdClient FunctionrequestOptionsThe requestOptions Objects maps to Fetch init parameter with some special considerations:
method will always be set based on the OpenAPI Specification method for this operationquery is a special property used to construct the final URLparams is a special property used to construct the final URL Path (Path Templating)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