This is a tree rendering of the OpenAPI specification (fka The Swagger Specification) to provide an easy to read visual documentation.
It has been created by Arnaud Lauret, the API Handyman.
This tool does NOT a render an API's OpenAPI specification.
You can see it on apihandyman.io
- Zoom in: Mouse scroll up
- Zoom out: Mouse scroll down
- Move: Mouse drag
- Clicking on a node expand or collapse it
- Moving mouse over a node shows its documentation
data contains sets of YAML files (one per version of the OpenAPI specification) describing each object provided by the OpenAPI specification. The content of these files is based on the OpenAPI specification itself, some precisions have been added when needed.
Info Object:
description: Provides metadata about the API. The metadata can be used by the clients if needed.
allowExtension: true
openapiType: true
fields:
- name: title
type: string
required: true
description: The title of the application.
- name: description
type: string
md: GFM
description: A short description of the application.
- name: termsOfService
type: string
description: The Terms of Service for the API.
- name: contact
type: Contact Object
description: The contact information for the exposed API.
- name: licence
type: Licence Object
description: The license information for the exposed API.
- name: version
type: string
required: true
description: Provides the version of the application API (not to be confused with the specification version).
The build (gulp) concatenes these files and converts the result in json in the .json file.
A D3JS tree is generated from the json file on runtime. All descriptions are converted from markdown to html.
The data/spec-versions.json define configuration for each version:
| Property | Description |
|---|---|
| name | The name that will appear in tabs |
| url | The json filename containing the data |
| root | The root object of this version |
| specificationurl | The md file URL for this specification |
[
{
"name": "2.0",
"url": "2.0.json",
"root": "Swagger Object",
"specificationurl": "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#"
}
]This project use:
- Bootstrap framework
- Handlebars templates
- Font Awesome icons
- Marked markdown parser and compiler
- YAML a human friendly data serialization standard for all programming languages.
- d3js tree
- The d3 tree is based on D3.js Drag and Drop, Zoomable, Panning, Collapsible Tree with auto-sizing. by Rob Schmuecker.
- The tooltip has been inspired by Adding tooltips to a d3.js graph by 3D Noob.
You need to install gulp in order to build the project:
npm install -g gulp-cli
Command lines to download project's dependancies:
npm install
Command line to build the project (generated files will be available in dist folder):
gulp
Command line to launch a local instance with automatic live reload if some files are modified:
gulp serve
This project is build by Travis CI and deployed on Github pages using the following files:
- .travis.yml: Travis CI Configuration file
- scripts/deploy.sh: Deploy script (which basically commits the result of the build on the gh-pages branch of this repository)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.