janrain / raml-fleece

Tool for converting RAML to HTML documentation

Purpose

raml-fleece turns RAML into a readable HTML file. It currently supports version 0.8 as defined in the 0.8 RAML specification

Key Features

• Sidebar containing all resources for easy navigation
• All headers are links
• Links produce readable URL fragments (e.g. http://example.com/api#GET/users)
• No collapsed elements make searching easy for browsers

Installation

npm install -g janrain/raml-fleece

Usage

raml-fleece api.raml > index.html

Custom Templates and Scripts

Custom Templates and scripts let you overwrite and extend the templates and scripts. See the command line help for details.

Thanks

This tool was originally built using raml2html.

raml-fleece's Issues

Markdown tables aren't rendered correctly

The html is generated correctly, but the table is missing the bootstrap table class.

Support null responses.

It appears there's a regression in #7

securitySchemes not rendering queryParameters

Looking at the RAML Spec, it seems that securitySchemes should accept and render queryParameters (see first example under Security). Could we add support for that?

From what I can see, the issue that we don't have anything for queryParameters in the template for securitySchemes:

raml-fleece/templates/security_scheme.handlebars

Lines 14 to 17 in 2b0a0a4

	{{#with describedBy}}
	{{#if headers}}
	{{> parameters type="Headers" params=headers}}
	{{/if}}

Is it just a matter of mimicking what's done for headers in the template?

Response code empty map renders as "undefined"

If the response has no special description (other than the standard response text), it should get rendered as such. The following is the valid raml example. Currently instead of "500: Server Error" this is rendering as "undefined"

#%RAML 0.8
title: Session Manager API
/session:
  post:
    responses:
      500: null

A response body with no example causes crash

Some RAML examples do not provide an "example" or "schema" for a response body.

When raml-fleece encounters this, it just crashes with:

TypeError: Cannot read property 'example' of null
at /opt/local/lib/node_modules/raml-fleece/src/main.js:106:19
at /opt/local/lib/node_modules/raml-fleece/node_modules/lodash/lodash.js:3579:27
...

render barks when response body content-type is not application/json

Just plain html-encoded rendering is probably good for non-application/json content types.

#%RAML 0.8
title: Minimal RAML
/:
  get:
    responses:
      500:
        description: A server error has occurred.
        body:
          text/plain:
            example: The database blew up!

Strangely, it renders the block, but it spits out an "invalid json" warning.

Render securedBy

securedBy does not get rendered.

get:
  description: Get identity data (including logged-in status) for this session
  securedBy: [signature,jwt]

Responses without bodies should render their descriptions

For example, the following delete method on a resource should probably show the descriptive content.

#%RAML 0.8
title: Minimal RAML
/:
  delete:
    description: Destroy the resource and all resource-bindings
    responses:
      204:
        description: Successfully deleted the resource consistent.
      404:
        description: No resource exists for the specified ID

Support for application/x-www-form-urlencoded mimetype

The vault api currently uses forms rather than json for request data.

Method navigation

For routes that support multiple request methods, it would be nice to have anchor links to subsequent methods at the top of the route documentation. Reciprocal links to the top of the route wold also be helpful.

For bonus points, add method selection functionality to the left column as well.

formParameters should be shown for x-www-url-encoded requests

A minimal raml sample:

#%RAML 0.8
title: Vault Scheduler
baseUri: http://scheduler.{securityGroup}.wault-janrain.com

/api/v1:
  post:
    description: |
      Reset the scheduler to a named snapshot. Specify the s3 location
      of the snapshot and the timeout for the download.
    body:
      application/x-www-form-urlencoded:
        formParameters:
          snapshot_url:
            type: string
            required: true
            example: s3://mybucket/mysnapshot
          timeout:
            type: string
            required: true
            example: 1m
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "message":"the system will restart now",
                "snapshot_url":"s3://my-bucket/my-snapshot"
              }

Markdown bullets aren't rendered

I tried both * and -, with and without indentation. The markdown is being used with !include from an external file. The bullets are rendered as an unstyled list, not sure if this is a bug or a feature...

Display json schema for request and response definitions

No content is shown. Not sure the best way to render it since a schema (altho "just json") certainly has contextual semantics. Maybe just rendering the json for now is fine?

#%RAML 0.8
title: Minimal RAML
/:
  get:
    body:
      application/json:
        schema: |
          {"$schema": "http://json-schema.org/schema",
                "description": "session identifier (v4 uuid without dashes)",
                "type": "string"}
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/schema",
                "description": "session identifier (v4 uuid without dashes)",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}[a-fA-F0-9]{4}4[a-fA-F0-9]{3}[a-fA-F0-9]{4}[a-fA-F0-9]{12}$"
              }

Preserve order of resources in RAML file

I would like to make a feature request to have an option to the CLI to preserve the order in which the resources are set in the input RAML file. Currently it appears they are written out in alphabetical order and we would like to use your tool but we have a specific order of API resources in our RAML for organizational structure.

Version parameter not displayed

The following example from the RAML spec should display the version number, but currently raml-fleece doesn't:

title: Salesforce Chatter REST API
version: v28.0
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

Instead, it currently just renders it as:

version [string] [required]