Skip to content

Convert any API Specification into an awesome HTML documentation website

Notifications You must be signed in to change notification settings

asfand-dev/api-html

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

35 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

API HTML

Convert any API Specification into an awesome HTML documentation website

Screenshot



Use the online tool

API HTML

Use CLI

Installation

npm i api-html -g



Usage

api-html --url https://petstore.swagger.io/v2/swagger.json

Demo

The above command will convert the given url into a static website in the current directory with the name of dist directory.

There is also a possibility to pass a file instead of url.

Params

Param Short Required Default Value Details
--file -f required null Path to a local source file, --file or --url on is required at same time.
--url -u required null URL to an online source file, --file or --url on is required at same time.
--type -t optional swagger Encoded type of the API specification, like swagger, openapi, api_blueprint, io_docs, google, raml or wadl
--version -v optional 2 Version of the OpenAPI (swagger), possible values are 1, 2 or 3. Only applicable to swagger
--yaml -y optional 0 If the source file type is yaml then the value should be 1, only applicable to swagger
--option -o optional ./options.json Path to the options file, see the details below

Example

  api-html --yaml 1 --url https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/yaml/api-with-examples.yaml
  # A Swagger (OpenAPI) version 2 source file with yaml type

  api-html --version 3 --url https://api.gettyimages.com/swagger/v3/swagger.json
  # A Swagger (OpenAPI) version 3 source file with json type

  api-html --version 3 --yaml 1 --url https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml
  # A Swagger (OpenAPI) version 3 source file with yaml type

  api-html --type api_blueprint --url https://raw.githubusercontent.com/apiaryio/api-blueprint/master/examples/Polls%20API.md
  # An API Blueprint source file

  api-html --type google --url https://www.googleapis.com/discovery/v1/apis/translate/v2/rest
  # A Google API descory source file

  api-html --type raml --url https://raw.githubusercontent.com/raml-apis/XKCD/master/api.raml
  # A RAML source file

  api-html --type io_docs --url https://raw.githubusercontent.com/lucybot/api-spec-converter/master/test/input/io_docs/foursquare.json
  # An IO Docs source file




Options (options.json)

The options should be in a json file, If you don't pass the --option parameter then we will check in the current directory with the name of options.json.

Name Default Value Description
theme compact Set the UI theme, values are: "compact" and "basic".
baseColor #6e9a04 Set the base color of the theme
textColor #FFF Set the text color of the theme
logo 'swagger-logo' Point a logo to a local file
logoUrl '' Point a logo to the URL
isCoding true Show or Hide the coding section in the request
isSearch true Show or Hide the Search feature
isTryRequest true Show or Hide the "try out" button in the request
isBackToTopButton true Hide or show the BackToTop button
isCreditLink true Hide or show the Credit link below the navigation bar
pageTitle the title from the swagger.json file Set the page title shown on browser title bar.
customHeadScript '' Add custom script to the head tag
customFootScript '' Add custom script to the foot tag
pageTags '' Represent the meta keywords of the page, Each keyword should be seperated by a comma. Meta Keywords are helpful for the page SEO.
pageDescription '' Represent the meta description of page
apiVersions '' API Versions, enter in the following format:
(Name)[URL]
(Name)[URL]
...
Exp:
(V1)[https://zamacall.io/docs/v1/]
(V2)[https://zamacall.io/docs/v2/]
headerMenuItems '' Header Menu Items, enter in the following format:
(Name)[URL]
(Name)[URL]
...
Exp:
(Main Website)[https://zamacall.io]
(Contact Us)[https://zamacall.io/contact/]

Example

{
  "logo": "logo.svg",
  "baseColor": "blue"
} 

Change log

  • Added A new Compact UI Theme; Nice, Clean, Faster and lightweight.
  • Added support for IO Docs source file
  • Added support for WADL source file
  • Added support for RAML source file
  • Added support for Google API Descory source file
  • Added support for API Blueprint source file
  • Added support for YAML source file
  • Added support for OpenAPI (swagger) version 1, 2, & 3.
  • Added the search functionality
  • Added support for trying the api request
  • Added support for code generation for languages like: cURL, Node, Python & JavaScript
  • Added an online tool to preview and download through online website
  • Added automatic description to the Authentication sections, will replace the empty descriptions.
  • Added support for small screens like mobile devices

Report an issue or request a feature

Github issues

Contact us

[email protected]