@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, 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 | URLSession