@readme/oas-to-snippet

Transform an OpenAPI operation into a code snippet. This library was built with ReadMe's reference guide offering in mind but it will support all OpenAPI use-cases.

Installation

npm install --save @readme/oas-to-snippet

Usage

import Oas from 'oas';
import oasToSnippet from '@readme/oas-to-snippet';
import petstore from './petstore.json';

const apiDefinition = new Oas(petstore);
const operation = apiDefinition.operation('/pets', 'get');

// This is a keyed object containing formData for your operation. Available keys
// are: path, query, cookie, header, formData, and body.
const formData = {
  query: { sort: 'desc' },
};

// This is a keyed object containing authentication credentials for the
// operation. The keys for this object should match up with the `securityScheme`
// on the operation you're accessing, and its value should either be a String,
// or an Object containing `user` and/or `pass` (for Basic auth schemes).
const auth = {
  oauth2: 'bearerToken',
};

// This is the language to generate a snippet to. See below for supported
// languages.
//
// For supplying an alternative language target (like `axios` for `node`), you
// can do so by changing this variable to an array: `['node', 'axios']`. For the
// full list of alternative language targets that we support, see below.
const language = 'node';

// This will return an object containing `code` and `highlightMode`. `code` is
// the generated code snippet, while `highlightMode` is the language mode you
// can use to render it for syntax highlighting (with `codemirror` for example).
const { code, highlightMode } = oasToSnippet(apiDefinition, operation, formData, auth, language);

Plugins

This library also supports the plugin system that we've built into HTTPSnippet. We have a plugin for generating snippets for ReadMe's API SDK generator and this is how you would integrate and generate snippets for it:

import oasToSnippet from '@readme/oas-to-snippet';
import httpsnippetClientAPIPlugin from 'httpsnippet-client-api';

const snippet = oasToSnippet(
  petstore,
  petstore.operation('/user/login', 'get'),
  formData,
  auth,
  // `[node, api]` is not a standard language in `oas-to-snippet` but is
  // dynamically made available via this loaded plugin.
  ['node', 'api'],
  {
    openapi: {
      registryIdentifier: '@petstore/v2.0#17273l2glm9fq4l5',
    },
    plugins: [httpsnippetClientAPIPlugin],
  },
);

Supported Languages

Since this library uses HTTPSnippet we support most of its languages and their associated targets which are the following:

Language	Available language mode(s)	Libraries (if applicable)
C	c	Libcurl
Clojure	clojure	clj-http
C++	cplusplus	Libcurl
C#	csharp	HttpClient, RestSharp
HTTP	http	HTTP/1.1
Go	go	NewRequest
Java	java	AsyncHttp, java.net.http, OkHttp, Unirest
JavaScript	javascript	XMLHttpRequest, Axios, fetch, jQuery
JSON	json	Native JSON
Kotlin	kotlin	OkHttp
Node.js	node	HTTP, Axios, fetch
Objective-C	objectivec	NSURLSession
OCaml	ocaml	CoHTTP
PHP	php	cURL, Guzzle, HTTP v1, HTTP v2
Powershell	powershell	Invoke-WebRequest, Invoke-RestMethod
Python	python	Requests
R	r	httr
Ruby	ruby	net::http
Shell	shell	cURL, HTTPie, Wget
Swift	swift	URLSession