@readme/oas-to-snippet
TypeScript icon, indicating that this package has built-in type declarations

24.0.2 • Public • Published

@readme/oas-to-snippet

Transform an OpenAPI operation into a code snippet.

Build

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 } = await 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 = await 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 NSURLSession

Readme

Keywords

none

Package Sidebar

Install

npm i @readme/oas-to-snippet

Weekly Downloads

567

Version

24.0.2

License

MIT

Unpacked Size

71.8 kB

Total Files

19

Last publish

Collaborators

  • gratcliff
  • dannobytes
  • gkoberger
  • domharrington
  • mjcuva
  • kanadgupta
  • jonursenbach
  • rafegoldberg
  • dashron
  • iliast