asfand-dev / api-html

Convert any API Specification into an awesome HTML documentation website

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]

api-html's Issues

Server Overwrite not works

Hi, first of all thanks for this tool, is really amazing.

I have the next problem:
some of my endpoints targets to another server. in openapi 3.0 you can overwrite/indicate the server to use.

When you converts it to html, the api with overwritten server not shows the rigth url.
could you help to fix that?

Json Open Api Example

Rendered api

Multiple Authentication Keys

Hi, this is a cool lib! accidentally stumbled upon looking for a good UI to show off apis.

So any tips on how to set multiple required authentication keys? Have the spec setup correctly and have the 'AUTHENTICATE' button when using swagger that allows me to authenticate 2 apikeys that is applied on all requests where I have parameter for each operation...

"security": [ {
          "x-client-key": [],
          "x-api-key": []
 } ],

I don't see in your UI or in options any global AUTHENTICATION and when I try it out on an endpoint with the 'security' parameter setup above the modal pops up with both keys ready for input but I can only AUTHENTICATE one key at a time.

This may be a hard problem to solve, stoplight elements has the exact same issue, however rapidoc allows me to set a global authenticate or setup my securityScheme with both keys and use the security above on the endpoint no probs.

Ill look to see if there is anything I can see in your lib that may help but if this is a bridge too far appreciate letting me know.

oneOf and allOf don't work

Hi!
Your api-html is cool. I like it. But it need some fix.

Api-html don't parse keywords oneOf and allOf. Here is link to swagger specification.

In my case, I have no model for request body in HTML. But source JSON contain it.

For oneOf it can be a dropdown to select a value. And show request body only for selected value.

My request body for example:

"requestBody": {
  "content": {
    "application/json": {
      "schema": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "my description 1",
                "minLength": 1,
                "maxLength": 255,
                "example": "BLACKFRIDAY2020"
              },
              "activation_limit": {
                "type": "integer",
                "description": "my description 3",
                "minimum": 1,
                "example": 500
              },
              "personal_activation_limit": {
                "type": "integer",
                "description": "my description 4",
                "minimum": 1,
                "example": 500
              }
            }
          },
          {
            "type": "object",
            "required": [
              "count",
              "length"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "description": "my description 5",
                "minimum": 1,
                "example": 100
              },
              "length": {
                "type": "integer",
                "description": "my description 6",
                "minimum": 1,
                "maximum": 255,
                "example": 10
              },
              "prefix": {
                "type": "string",
                "description": "my description 7",
                "example": "prefix",
                "minLength": 0,
                "maxLength": 254
              },
              "charset": {
                "type": "string",
                "description": "my description 8",
                "example": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
              }
            }
          }
        ]

Rendering model for array of objects

The scheme in the rendered HTML has an empty model when it contains array of objects.

Example attached
swagger.txt

certificate has expired

Hi,
I try api-html --type api_blueprint --file info.apib and get this error:

Error: certificate has expired
at TLSSocket.onConnectSecure (node:_tls_wrap:1530:34)
at TLSSocket.emit (node:events:390:28)
at TLSSocket._finishInit (node:_tls_wrap:944:8)
at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:725:12) {
code: 'CERT_HAS_EXPIRED'

What can I do?

Is it possible to add parameters for the output file?

Hello,

This is an awesome project.

I have many json files.
I want add api-html to a pipeline in the CD progress.
But I got a problem, when I execute api-html --file xxx.json.
It will output dist/index.html, not dist/xxx.html.

It would be better if the output file name is the same as the original file.
Or you can add a parameter to customize the output file name.

Thank you.

Error: certificate has expired

Hi,
I just installed it through npm and tested it with following options:
npx api-html --type openapi --version 3 --yaml 1 --file ./openapi.yaml

It answers with following error:

/data/scm/MyProjects/isotopviz-specs/node_modules/api-html/utils.js:5 throw msg; ^ Error: certificate has expired at TLSSocket.onConnectSecure (node:_tls_wrap:1530:34) at TLSSocket.emit (node:events:394:28) at TLSSocket._finishInit (node:_tls_wrap:944:8) at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:725:12) { code: 'CERT_HAS_EXPIRED' }

I have no idea from where that certificate error come from or what I did wrong ...
Any clue ?

Regards,

ECONNREFUSED when attempting to generate html

api-html\utils.js:5
  throw msg;
  ^

Error: connect ECONNREFUSED 85.215.225.50:443
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1161:16) {
  errno: -4078,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '85.215.225.50',
  port: 443
}

This is what happens when you try to run the tool.

It looks like you try to connect to https://openapi.one/_/api/v1/documentation/html, which no longer responds.

I don't think an API Documentation tool should be relying on a remote domain in order to generate the result. Consider including whatever files are required to generate the html within the module itself.

Expired certificate

Hello,

When running npx api-html -v 3 -f backend/spec/swagger.json I encounter the following error:

Error: certificate has expired
    at TLSSocket.onConnectSecure (node:_tls_wrap:1532:34)
    at TLSSocket.emit (node:events:527:28)
    at TLSSocket._finishInit (node:_tls_wrap:946:8)
    at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:727:12) {
  code: 'CERT_HAS_EXPIRED'

Is there anything I can do to work around the issue?
Thanks