Lincoln

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

This project is inspired by ReDoc, which currently handles Swagger v2 specs.

This project is in an early phase of development.

Prerequisite

• Node.js is required to build and manage this project.
• It is assumed that you use yarn to manage Node.js dependencies and to run scripts. You're welcome to use npm, in which case, just substitute yarn with npm.

Installation

yarn

Usage

Lincoln as a component

To use Lincoln in your React project:

import Lincoln from 'react-lincoln'

<Lincoln definitionUrl='https://temando.github.io/open-api-renderer/petstore-open-api-v3.0.0-RC1.json' />

This represents a future state, Lincoln is not published to NPM yet.

Lincoln demo

To preview Lincoln on your local machine:

yarn run start

Lincoln is now available on http://localhost:8200. The port can be changed by updating webpack.config.dev.

You need to specify a url for the Open API v3 file, e.g. http://localhost:8200?url=https://temando.github.io/open-api-renderer/petstore-open-api-v3.0.0-RC2.json

Configuration

The following configuration options apply to the Lincoln component:

property	required	type	description
definitionUrl	✔	string	CORS-enabled URL to Open API v3 definition to render. Supports JSON or YAML.
navSort		enum	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.

Building & Deployment

To build this project as React component:

yarn build:library

To build the demo located in /docs/demo:

yarn build:demo

You can deploy the files at /docs/demo to your server.

Philosophy

While this project is currently focused on visualising Open API 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 Open API 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 us make it a reality. For contributing information, see CONTRIBUTING.md.