tobilg / api2html Goto Github PK

View Code? Open in Web Editor NEW

113.0 6.0 25.0 287 KB

A CLI tool to transform Swagger/OpenAPI/AsyncAPI docs to beautiful HTML pages via Shins/Widdershins.

License: MIT License

JavaScript 100.00%

openapi openapi3 slate static-site-generator api-documentation swagger-documentation asyncapi

api2html's Introduction

api2html

A CLI tool to transform Swagger/OpenAPI/AsyncAPI docs to beautiful HTML pages via Shins/Widdershins.

You can find an example generated page at http://tobilg.github.io/api2html/petstore/.

Installation

To install api2html globally, use

$ npm i api2html -g

You can also install it to use as devDependencies, and use it locally via a npm run task in your package.json:

$ npm i api2html --save-dev

Usage in package.json:

{
  "scripts": {
    "api-docs": "node_modules/.bin/api2html -o docs/api.html -l shell,javascript--nodejs docs/openapi/api.yml"
  }
}

Usage

Available commands

$ api2html --help 
Usage: api2html [options] <sourcePath>
  
  Options:
    -V, --version                   output the version number
    -r, --resolve <source>          resolve external dependencies, source should be a url or a path
    -o, --out <outputPath>          output path for the resulting HTML document
    -t, --theme <themeName>         theme to use (see https://highlightjs.org/static/demo/ for a list)
    -c, --customLogo <logoPath>     use custom logo at the respective path
    -u, --customLogoUrl <logoURL>   url for the custom logo to point to
    -C, --customCss                 use custom css
    -P, --customCssPath <cssPath>   use custom css file
    -i, --includes <includesList>   comma-separated list of files to include
    -l, --languages <languageList>  comma-separated list of languages to use for the language tabs (out of shell, http, javascript, javascript--nodejs, ruby, python, java, go)
    -N, --noCodeSamples             omit all code samples (overrides --languages)
    -s, --search                    enable search
    -S, --summary                   use summary instead of operationId for TOC
    -b, --omitBody                  Omit top-level fake body parameter object
    -R, --raw                       Show raw schemas in samples, not example values
    -h, --help                      output usage information

Usage examples

Render OpenAPI v3 file as HTML

This will render the api.yml file in the current directory as myapi.html file in the current directory.

$ api2html -o myapi.html myapi.yml

Use custom logo

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use the custom logo mylogo.png.

$ api2html -o myapi.html -c mylogo.png myapi.yml

Define which language examples should be generated

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use go and javascript examples.

$ api2html -o myapi.html -l go,javascript myapi.yml

Use different syntax highlighter

This will render the api.yml file in the current directory as myapi.html file in the same directory, and use go and javascript examples, as well as a different syntax higlighter from highlight.js.

$ api2html -o myapi.html -l go,javascript -t arta myapi.yml

Resolve external dependencies

If you add refs to external files in your source file, you can enable them by using -r <source>. The following command will resolve all your relative imports from the current directory.

$ api2html -o myapi.html -r ./ myapi.yml

api2html's People

Contributors

Stargazers

Watchers

api2html's Issues

Update NPM package

Hello,

Since you merged our PRs, don't forget to update/republish the npm package.
Cheers :)

Ability to specify Widdershins environment/config file

Is there a way to specify a Widdershins config file, used by --environment? There are a number of things that would be nice to specify and have passed on to Widdershins without having to have api2html support every single thing Widdershins supports.

When converting examples output shows new line identifier.

When converting, running this on our yaml spec, we have a few code examples that when converted to html are not encoding new lines and are outputting as a single line with a bunch of \n .

Don't see how to use customCss

Hey there!

Just trying this out on a project I am firing up and it's working pretty great!

One requirement I have is to add some custom CSS (or even Sass). Currently the customCss flag appears to be a boolean value of true, which is passed through to shins.

According to the shins docs

Setting customCss to true will include the pub/css/screen_overrides.css,pub/css/print_overrides.css and pub/css/theme_override.css files, in which you can override any of the default Slate theme, to save you from having to alter the main css files directly. This should make syncing up with future Shins / Slate releases easier.

But we don't have any way to access these files as they are in node_modules using this tool.

How do I inject customCss?

Thanks!

Restrictions always none

Hi
I am using this tool to generate a swagger 2 api document, but I cannot see any Restrictions in the generated html.
I added minLength, maxLength, I think these are restrictions.

Is this a bug? Can you give some suggestions for this problem?

How to use --theme

I am trying to use the --theme option.
I cant see any error but i cant see any visual difference.
Where is my error?

api2html -o ./dist/api.html --languages http,javascript,javascript--nodejs --theme idea ./dist/api.yaml

Thank you

combine schemas not working in 'paths'

combining schemas in path is not working
e.g.

paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'

but it's working in

components:
  schemas:
  ...

Example language typescript

Hello!
Thank you for this great project.

Is it possible to generate examples for Typescript? (eg. -l typescript)

Greetings!

theme question

edit: my bad on the error, -theme needs to be --theme

Also, it's not clear if there's a way to change the .toc-wrapper / dark parts of the theme? I'm assuming "theme" is just the middle section?

Update npm package

I noticed the customLogoUrl CLI option isn't available on the NPM package that is published. Just curious when this might be available.

Thanks!

Properties aren't being lifted for schemas

Let's say that I have a schema defined in my OpenAPI spec:

  user:
    properties:
      id:
        type: string
        format: uuid
      login:
        type: string
        format: email
      password:
        type: string
        format: password

I would expect in the generated HTML to include only the properties, so basically this:

{
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "login": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "format": "password"
    },
}

However, it is rendering with the higher level fields:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "login": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "format": "password"
    }
  }
}

You can also see this happening the example you link to in the README: https://tobilg.github.io/api2html/petstore/#schemas

Appending requestBody to curl samples

Hello! First of all, thanks for this awesome package! It's just so really helpful in producing excellent API documentation.

I just wanted to reach out to ask if there's a way I can append the form-data params to the curl examples. Right now, requestBody that are of multi-part form data and application/json content types show in the curl samples if httpsnippet and experimental options are hardcoded to true, but not params with x-www-form-urlencoded content-type. Any help is much appreciated.

Thank you in advance!

Suggestions and a question

Hi Tobi:

Thanks for maintaining this project!

I see reason to add several new arguments to pass on to shins.render() like, layout, etc. and maybe a verbose option to log which options were recognized and being passed on to the converter and the renderer. Any/all would be helpful.

In looking at the command line argument definitions, in the current version, you have two -s options, although the -- options are different. That might be worth fixing.

Also, do you when the current version would be synced with npm? Seems like the customcss option isn't out there yet.

Thanks,

Matt