jekyll-ramler
Generates Jekyll pages for overview, security, and resource documentation specificed in a RAML file.
Features
- Renders RAML into multi-page HTML views - one page per endpoint
- Supports rendering multiple RAML files into web pages
- Transforms description fields found in RAML via Markdown
- Auto-generation of JSON Schema based on existing formParamters of application/x-www-form-urlencoded
- Generation of complete RAML and JSON representations of API descriptors
- Supports Raw and Table based displays of JSON Schema included in your RAMLs
- Automatic insertion of inherited JSON Schema (via
$ref
andallOf
)
Example
GovDelivery's developer documentation site, http://developer.govdelivery.com, is built on jekyll-ramler, jekyll-code-example-tag, and jekyll-nested-menu-generator.
For an example of the output generated by jekyll-ramler, please visit GovDelivery's TMS API documentation at http://developer.govdelivery.com/api/tms/.
Installation
Dependencies
jekyll-ramler relies on raml-cop, a
Node.js script, to actually parse a RAML file. Thus, you will need to install
Node.js, then perform npm install raml-cop
.
Configuration
Several options can be defined by your project's _config.yml:
- ramler_api_paths
A nested mapping of the files that jekyll-ramler should read while generating content and the web folders where that content should be placed. Keys are the file system paths (relative to your project's root directory) of the files to be read. Values are the web paths (relative to web root) to place all content generated based on the read file into. Keys must end with a forward slash. If no value is provided, web root (/) is used.
Behavior is undefined for cases in which jekyll-ramler is configured to output generated content of multiple source files to the same web path.
If ramler_api_paths is not defined, jekyll-ramler will default to reading
api.json
from your project's root and placing generated files into web
root.
At this time, only JSON representations of RAML can be read.
Example:
ramler_api_paths:
ramls/api_v1.json: /an_api/v1/
ramls/api_v2.json: /an_api/v2/
ramls/api_v3.json: /an_api/
ramls/api_v3.json: /an_api/v3/
experimental/foo.json: /unstable/
ramls/popular.json: /
- ramler_generated_sub_dirs
A nested map defining the web sub directories that jekyll-ramler will place generated pages into. Can have three mappings:
- resource - web sub directory for resource pages. Defaults to
resource
. - overview - web sub directory for overview pages. Defaults to
overview
. - security - web sub directory for security pages. Defaults to
security
.
Example:
ramler_generated_sub_dirs:
resource: resources_pages
overview: general_documentation
security: security_information
The same value can be used in multiple mappings. For example, all three
mappings could be set to documentation
.
- ramler_downloadable_descriptor_basenames
A nested map defining the basename of the generated, downloadable descriptors
(RAML and JSON). Format is similar to ramler_api_paths
, where the keys
are file system paths of files to be read, while values are the basenames
to use for generated descriptors. For example:
ramler_downloadable_descriptor_basenames:
ramls/api_v1.json: api_v1
experimental/foo.json: unstable
will lead to the creation of api_v1.raml
, api_v1.json
, unstable.raml
,
and unstable.json
downloadable files.
If a basename is not defined, api
is used as a basename.
Generated descriptor files will be placed in the web folder configured for a given source file.
Markdown no_intra_emphasis
All description values found in a RAML file are transformed via Markdown, which allows underscores (_) to be used as deliminators for emphasis and bold content. Default transformation behavior can lead to mis-transformed content, especially for words that contain underscores, such as variable names. As such, it is recommended that you use the no_intra_emphasis extension of your choosen Markdown engine. This extension can be enabled for Redcarpet by adding the following to your _config.yml:
markdown: redcarpet
redcarpet:
extensions: ["no_intra_emphasis"]
Refer to http://jekyllrb.com/docs/configuration/#markdown-options for more information on the use of no_intra_emphasis in Jekyll.
Markdown Descriptions
jekyll-ramler will transform any description value found in a RAML via
Markdown. This includes description values on endpoints, methods, security
schemas, and in formParameters items. body values of documentation
entires
will also be transformed via Markdown.
Note that in order to use Markdown in the description of a formParameter item, you will need to use the pipe syntax (|) to avoid a RAML validation error.
JSON Schema Support
jekyll-ramler includes a few features for JSON Schema.
Table and Raw views of JSON Schema
If a resource method defines body:application/json:schema
item, then
jekyll-ramler will generate two views of the schema. One view will be an
easily copyable display of the raw schema. The other view will be a table-like
display of parameters, similar to what is generated for
body:application/x-www-form-urlencoded:formParamters
.
Generated JSON Schema from formParameters
Recognizing that Content-Type does not impact functionality or content for some
APIs, jekyll-ramler will generate JSON Schema for resource methods that include
a defined body:application/x-www-form-urlencoded:formParamters
list, as well
as a body:application/json
item without a schema
item. If a resource
includes a body:application/json/schema
item, then nothing will happen.
$ref and allOf
JSON Schema provides a semantic construct for schema inheritance via the $ref and allOf keywords. jekyll-ramler uses this construct to allow for schema referred to in RAML to inherit from other schema, which allows you to DRY your JSON schema bit.
When jekyll-ramler encounteres $ref and/or allOf, it pulls in and merges the referred to schemas, creating a single schema object that includes all attributes. Thus, while you might store your JSON schema across multiple files, users of your site will only see fully de-referenced and merged JSON schema on your site. This de-referencing and merging also allows jekyll-ramler to generate complete, table-like views of your JSON schema, even if your schema inherits from other schema.