OpenAPI Specification Visual Documentation

This is a prototype of a D3 rendering of the OpenAPI specification (fka Swagger Specification) to provide an easy to read visual documentation. It is developed by Arnaud Lauret, the API Handyman.

This is NOT a rendering of an API OpenAPI specification.

How to use it?

You can see a live demo 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

How does it work?

app/openapi-specification contains a set of YAML files 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
      gfm: true
      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).

All these files are concatened in openapi-specification.yaml and then converted in openapi-specification.json.

A tree is generated from the json file on runtime. All descriptions are converted from markdown to html.

Tools used

This project has been created and built with:

Yeoman and the gulp-webapp generator.
npm
bower

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.

How to build and modify

You need to install gulp and bower in order to build the project:

npm install -g gulp
npm install -g bower

Command lines to download project's dependancies:

npm install
bower 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

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