react-lincoln

Lincoln

Meet Lincoln, a React component for rendering OpenAPI documents. The project is tracking against v3.0.0 of the OpenAPI specification.

Lincoln aims to support evergreen browsers, such as Chrome, Firefox, Safari and IE11+. It is responsive and should be usable on most modern devices.

Demo

Installation

npm install --save react react-dom react-lincoln

Usage

To use Lincoln in your React project:

import React from 'react'
import ReactDOM from 'react-dom'
import Lincoln from 'react-lincoln'
 
ReactDOM.render(
  <Lincoln definitionUrl='https://temando.github.io/open-api-renderer/petstore-open-api-v3.0.0-RC2.json' />,
  document.body
)

Alternatively, you can pass the contents of the definition directly to Lincoln:

import React from 'react'
import ReactDOM from 'react-dom'
import Lincoln from 'react-lincoln'
import definition from './myApi.yml'
 
ReactDOM.render(<Lincoln definition={definition} />, document.body)

Configuration

The following configuration options are available:

property	required	type	description
definitionUrl or definition	✔	string	CORS-enabled URL to, or contents of, OpenAPI v3 document to render. Supports JSON or YAML.
navSort		enum	This property applies when your definition uses tags. Valid values are alpha which sorts by HTTP method, then path or false, which will display paths as defined. Defaults to false.
validate		boolean	If true, uses Mermade to validate definition. Defaults to false.
initialSchemaTreeDepth		number	The initial opened tree depth for schema visualiser when first rendered. This is useful when the schema's actual contents is a couple of levels deep, and you want to expand the tree to the contents automatically. Defaults to 0.
navigationMethodDisplayType		string	Regulates how the navigation items are rendered - path only, summary only, or both. The possible values are summary (default), path, or all. In case of any other value only the summary is rendered.

Philosophy

While this project is currently focused on visualising OpenAPI V3 specifications, it is architected in such a way that the React components deal with a UIReadySchema, which is a generic specification (admittedly heavily based on OpenAPI V3).

The dream is that this renderer could visualise other formats by introducing new parsers which transform documents into the common UIReadySchema format. This approach allows us to build something sustainable and scalable, where the community can help contribute new parsers (among other things!) as required.

The project is definitely in its infancy and we are not ready for that yet, but we hope by sharing this vision early, others can help make it a reality. For contributing information, see CONTRIBUTING.md.

Credit

• The ReDoc project inspired Lincoln. If you're looking for an alternative renderer, give ReDoc a try!
• swagger2openapi which Lincoln uses to validate definitions.

Maintainers

Lincoln is an open source project from Temando's Developer Experience team. Temando connects carriers with retailers and retailers to people. The Temando Platform combines shipping experiences, multi-carrier connectivity and lightning fast fulfillment in one solution. If this sounds like fun, work with us!