/api-raml

Tools involved reading RAML files. For example, generation of api proxy files and processing Covisint RAML extensions.

Primary LanguageRuby

api-raml

An API documentation build and browse tool which uses Docker and Mulesoft's api-console. This uses a custom RAML reader (it is too basic to be called a parser) and a Dockerfile to build and run a custom api-console which can be used to explore the generated documentation.

Prerequisites

  1. Docker (Or Boot2Docker for Mac or Windows)

Usage

(Note: For a simpler alternative, have a look at the "Simplified usage" section below.)

To generate version-specific documentation and to run api-console to browse them, run the following from the directory containing the RAML files you want to use.

$ docker pull venkytv/covisint-api-console
$ docker run -it --rm -v "$PWD":/raml -p 9000:9000 venkytv/covisint-api-console

The first time you run the docker run command, it will download a bunch of container layers. This might take some time. These layers get cached locally, so subsequent runs should be much faster.

Now, browse the generated documentation on your local machine.

In case you are are unable to access the api-console on Mac or Windows, make sure that the VM IP has not changed using the boot2docker command.

    $ boot2docker ip
    192.168.59.103

Generating version-specific RAML files

To just generate version-specific RAML files without launching api-console, pass the "genraml" argument to the docker command line. This will create a dist/raml/versions directory within your current directory and store the RAML files within versioned directories there.

$ docker run --rm -v "$PWD":/raml venkytv/covisint-api-console genraml

If the current directory contains a release-manifest.yml file (example), the command will also create a dist/raml/releases directory and copy the RAML files into release-specific subdirectories.

Generating CSV descriptions of RAML files

To just generate CSV descriptions of RAML files without launching api-console, pass the "gencsv" argument to the docker command line. This will create a "dist/csv" directory within your current directory and store the CSV files within.

$ docker run --rm -v "$PWD":/raml venkytv/covisint-api-console gencsv

Generating the api-console war file

To generate a war file for deployment into the developer portal, pass the "genwar" argument to the docker command line. This will create an "api-console.war" file under the "dist" directory within your current directory.

$ docker run --rm -v "$PWD":/raml venkytv/covisint-api-console genwar

Advanced

To override the hostname part of the baseUri in the generated RAML files, set the baseuri variable.

$ docker run --rm -v "$PWD":/raml \
  -e "baseuri=example.com" venkytv/covisint-api-console genraml

By default, the tool collapses empty nodes in the filtered RAML files. To disable this behaviour, set the collapse_empty variable to false for the docker run.

$ docker run -it --rm -v "$PWD":/raml -p 9000:9000 \
  -e "collapse_empty=false" venkytv/covisint-api-console

Debugging

To drop into a shell within the docker container after generating the custom RAML files, pass the "bash" argument to the command line:

$ docker run -it --rm -v "$PWD":/raml -p 9000:9000 venkytv/covisint-api-console bash

If there is a problem generating the custom RAMLs itself, the previous command might fail. In that case, do the following:

$ docker run -it --rm -v "$PWD":/raml -p 9000:9000 \
  --entrypoint=bash venkytv/covisint-api-console --

This will drop you into a shell inside the container. Now, you can run the parser script manually by hand to debug the issue:

# /api-console/ramlparser.rb /raml /tmp /raml/release-manifest.yml

The parser and all the supporting scripts are inside the /api-console directory. The container does not include an editor; so, if you want to edit any of the files, you need to install an editor:

# apt-get install vim

REMEMBER: Any changes you make within the container are lost the moment you exit the shell. The container is re-created afresh every time you do a "docker run" and removed as soon as the command exits. If you make any changes to the scripts under /api-console, make sure the changes are also made in the corresponding scripts in the api-raml git repo under the docker/ directory.

Simplified usage

The util/api-console script provides a simpler way to invoke all the above commands. It requires ruby and the colorize gem (gem install colorize).

Examples:

Bring up the api-console using the RAML in the api-doc submodule:

$ util/api-console

Use RAML files located in a different directory:

$ util/api-console ~/my-raml-files

Point the api-console to a specific Apigee instance/environment:

$ util/api-console -l     # List available Apigee environments
$ util/api-console prod   # Point the api-console to the production instance

Bring up the api-console on a specific port (default: 9000):

$ util/api-console 9000

Do a docker pull before execution:

$ util/api-console -p

Generate the api-console war file:

$ util/api-console genwar

Drop into a shell inside the docker container:

$ util/api-console bash

Multiple options:

$ util/api-console prod genwar  # Generate war file for production instance
$ util/api-console -p ~/my-raml-files rnd 9002  # Pull docker image, use custom RAML files, map to port 9002

Usage help:

$ util/api-console -h

Building the docker image

You should be able to just pull the docker image from Docker Hub, but in case you want to build the image locally, do the following:

$ cd docker
$ docker build .  # Don't miss the "." at the end