JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 47
  • Score
    100M100P100Q87687F
  • License MIT

Feed it a JSON Spec, it will spit out a lightweight HTTP client!

Package Exports

  • oas-request
  • oas-request/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (oas-request) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

OpenAPI Spec HTTP Client

Feed it a JSON Spec, it will spit out a lightweight HTTP client!

license release semantic

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 calling oas-rqeuest

    Example
    using YAML
    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)
    using apidevtools/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 of URL
  • options.query will be processed to construct the url, 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