OpenAPI Map

The OpenAPI Map (fka. OpenAPI Specification Visual Document) aims to help you find your way in the OpenAPI Specification (fka. Swagger Specification) documentation. Note that it is not made to render an OpenAPI document.

It has been created by Arnaud Lauret, the API Handyman.

How to use it?

You can see it on openapi-map.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

How does it work?

Configuration

The data/spec-versions.json file, loaded when index.html is load by browser, lists OpenAPI versions which are visible in top right navigation bar:

[
  {
    "name": "Version 3.0",
    "id": "3.0",
    "url": "3.0.1.json",
    "root": "OpenAPI Object",
    "specificationurl": "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md"
  },
  {
    "name": "Version 2.0",
    "id": "2.0",
    "url": "2.0.json",
    "root": "Swagger Object",
    "specificationurl": "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md"
  }
]

The data of each version comes from a <version>.json file defined in url. This file has been generated on build based on data yaml files from folder data/<version>. The data contains informations coming from the specification available at specificationUrl.

Data files

The data folder contains sets of YAML files (one per version of the OpenAPI Specification) describing each object provided by the OpenAPI Specification.

data
├── 2.0
│   ├── Contact_Object.yaml
│   ├── Definitions_Object.yaml
    ...
│   ├── Swagger_Object.yaml
│   └── Tag_Object.yaml
└── 3.0.1
    ├── Callback_Object.yaml
    ├── Components_Object.yaml
    ...
    ├── OpenAPI_Object.yaml
    ...
    └── XML_Object.yaml

The content of these files is based on the OpenAPI Specification itself, some precisions have been added when needed.

Some Object:
  description: |
    This is `Some Object`' description,
  allowExtension: true
  changelog:
    isNew: true
    details: Contains former root `responses`, `parameters` (split into `parameters` and `requestBodies`) and `definitions` (as `schemas`).
  fields:
    - 
      name: schemas
      type: "{Schema Object}"
      changelog:
        isInfo: true
        details: Replace root `definitions`
      description: An object to hold reusable [Schema Objects](#schemaObject).

Data file structure

About descriptions

All description properties can contain markdown. If a description contains some links, they are modified that way:

• A target=_blank is added to all links
• Anchor links coming from the specification, like this [Schema Objects](#schemaObject) are modified to target the specificationurl provided in version's configuration
• Links to ../examples are update to target the OpenAPI github repository according to the specificationurl provided in version's configuration

Build and modify

Prerequisites

You need to install gulp and mocha and download dependencies in order to build the project:

npm install -g gulp-cli
npm install -g mocha
npm install

Commands

Code notes

Tools used

This project uses:

• Gulp to automate development tasks
• Mocha to test the JS code
• Bootstrap framework to lessen the pain of doing HTML and CSS
• Handlebars templates for the left panel showing the documentation
• Font Awesome icons
• Marked to convert markdown descriptions in HTML
• YAML a human friendly data serialization standard for all programming languages to store the OpenAPI Map data
• d3js to draw the map
  • 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.

CI and Hosting

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)

WARNING: Do not forget to update the web/CNAME file when changing Github Page domain using the Github admin.

Licence

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.