Warning

@readme/oas-to-snippet has moved! The source for this library now lives at https://github.com/readmeio/oas.

@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 `registryIdentifier` option is only necessary when using the `['node', 'api']` language
// combination. It controls how these snippets are used according to the code generation tooling
// that we offer with https://api.readme.dev/.
const registryIdentifier: '@petstore/v2.0#17273l2glm9fq4l5';

// 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 @readme/syntax-highlighter, for example).
const { code, highlightMode } = oasToSnippet(apiDefinition, operation, formData, auth, language, { openapi: registryIdentifier });

Supported Languages

Since this library uses HTTP Snippet, 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	api, HTTP, Request, Unirest, 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	NSURLSession