Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/temando/open-api-renderer
🎩 A React renderer for OpenAPI v3.
https://github.com/temando/open-api-renderer
open-api open-api-v3 openapi react swagger
Last synced: 7 days ago
JSON representation
🎩 A React renderer for OpenAPI v3.
- Host: GitHub
- URL: https://github.com/temando/open-api-renderer
- Owner: temando
- License: mit
- Created: 2017-03-27T22:26:14.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-03-05T18:56:04.000Z (over 5 years ago)
- Last Synced: 2024-10-31T07:51:34.533Z (14 days ago)
- Topics: open-api, open-api-v3, openapi, react, swagger
- Language: JavaScript
- Homepage: https://temando.github.io/open-api-renderer/demo/?url=https://temando.github.io/open-api-renderer/petstore-open-api-v3.0.0-RC2.json
- Size: 4.16 MB
- Stars: 148
- Watchers: 11
- Forks: 10
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Lincoln
[](https://npmjs.org/packages/react-lincoln/)
[](https://travis-ci.org/temando/open-api-renderer)
[](https://en.wikipedia.org/wiki/MIT_License)
[](https://standardjs.com)
Meet Lincoln, a [React](https://facebook.github.io/react/) component for rendering [OpenAPI](https://www.openapis.org) documents. The project is tracking against [v3.0.0](docs/open-api-v3-support.md) 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](https://temando.github.io/open-api-renderer/demo/?url=https://temando.github.io/open-api-renderer/petstore-open-api-v3.0.0-RC2.json)
## Installation
```sh
npm install --save react react-dom react-lincoln
```
## Usage
To use Lincoln in your React project:
```js
import React from 'react'
import ReactDOM from 'react-dom'
import Lincoln from 'react-lincoln'
ReactDOM.render(
,
document.body
)
```
Alternatively, you can pass the contents of the definition directly to Lincoln:
```js
import React from 'react'
import ReactDOM from 'react-dom'
import Lincoln from 'react-lincoln'
import definition from './myApi.yml'
ReactDOM.render(, 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](https://openapi-converter.herokuapp.com/) 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](CONTRIBUTING.md).
## Credit
- The [ReDoc](https://github.com/Rebilly/ReDoc) project inspired Lincoln. If you're looking for an alternative renderer, give ReDoc a try!
- [swagger2openapi](https://github.com/mermade/swagger2openapi) which Lincoln uses to validate definitions.
## Maintainers
Lincoln is an open source project from [Temando](http://temando.com/)'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](http://temando.com/en/about/careers)!