Generate Api documentation using YAML
version: 0.4.2 --- wizards: name: Management endpoints: - get: /wizards listWizards info: Finds all of the wizards that are available, sorted by hat size - post: /wizard createWizard info: Gives birth to a new wizard setting their name & (optionally) hat size body: name: string - What to call the wizard hatSize?: number - How big to make his hat responses: - 200: Success created.json
Docs are rendered to
spec.json in your output directory, which is
docs by default. If there are compilation errors they are rendered instead.
- Using the CLI
- Writing Docs
- Custom Templates
Using the CLI
# Install for your project npm install --save-dev ocelot-docs # Run inside your project npx ocedocs --help # Generate documentation npx ocedocs --input apispec --output apidocs # Watch the docs (regenerates the docs on page load) npx ocedocs -w
You write you doc specification in its own directory, which defaults to
api/. There should be an
info.yml in that directory which describes your api, it can have a
template refers to an npm package defining the api template, see Custom Templates.
name: Wizards Api # template: my-custom-npm-template description: > A simple API for creating & managing those pesky wizards
Ocelot expects each version of your api to be in its own directory inside your input directory, e.g.
1.0.0/, but you can have a single version at the root if you want. Ocelot sees any directory with an
endpoints.yml file in as an api version.
wizards: base: /wzrd name: Wizards endpoints: - id: index method: get url: /list name: Fetch Wizards info: Looks for all wizards and sorts them by hat size - post: /new create name: Create Wizard body: name: string - The name of the wizard
||The name of the group|
||optional – A base url for this group, relative to the version's base|
||The list of endpoint definitions|
An endpoint is a specific url & http method that performs some logic in your api and returns a response.
||An identifier for the endpoint|
||The http method to access the endpoint|
||The url to access the endpoint, relative to the group|
||The name of the endpoint|
||optional – A longer description of the endpoint|
||optional – A list of Response Definition|
||optional – The url parameters e.g.
||optional – The query parameters e.g.
||optional – The json/form body parameters, an Argument Definition|
As seen at the very top, you can use the endpoint shorthand which defines the
id in one go. The equivalent of the previous example would be:
endpoints: - get: /list index name: Fetch Wizards info: Looks for all wizards and sorts them by hat size
An argument definition is a YAML object with descriptions for a set of arguments. They key is the name of the argument and the value is a string definition containing the type, a dash (
-) and the description. If the key ends with a
?, it is marked as optional.
name: string - The name of the wizard age?: number - An optional age of the wizard
- 200: Success index/success.json - 404: Not Found index/failed.json
A response definition is an array of objects which describe potential responses that the endpoint can return. It is in three parts, the key is the http
status code, the first part is the human-friendly
name and the last is the
body, a reference to a file with an example json response in.
nameis a friendly name of this response
statusis the http status code this response comes with
bodyis a reference to a file which contains the example body (a json file)
To look for the body it will look look in
data/ directory relative to your
When writing an
endpoints.yml file, you can optionally define a version block at the top which defines meta information about this version of your api.
version: 0.0.1 base: / groups: - wizards - witches - misc --- wizards: # An endpoint group ...
||The name of this version|
||optional – The base url for this version, all endpoints will be under this|
||optional - The order of the endpoint groups in this version, an array of strings|
A template is an npm package used to render an api definition using pug. The package should have a
template/ directory which should contain:
info.yml– A file containing info about the template
index.pug– A pug template to render the api definition
error.pug– A pug template to render errors or warnings
name: Custom Template version: 0.1.2 link: https://example.com assets: - js - css - img
||The name of the template|
||The version of the template|
||A link to the template's author|
||optional – A list of directories that will be copied into the compiled result|
For more info, see the default template. There is also the
spec.json, which is created along side your
index.html, which is used to render the docs.