A script has been added to generate REST endpoint documentation from
a source CSV file. See _posts_templates/endpoint.md
and
posts_templates/endpoints.csv
for an example.
The script is prepareposts.py
. Run it from the project directory,
and takes the documentation bits from the cells in the CSV and inserts
them into the template to create multiple endpoint documentation files.
The resulting files are written to _posts
. Run the script before
starting Jekyll, and if you modify the templates or source CSV, you
must stop Jekyll, re-run prepareposts.py
, and start Jekyll again.
The rest of this readme is the upstream text.
Carte is a simple Jekyll based documentation website for APIs. It is designed as a boilerplate to build your own documentation and is heavily inspired from Swagger and I/O docs. Fork it, add specifications for your APIs calls and customize the theme. Go ahead, see if we care.
We built Carte because the existing options (Swagger and the likes) were trying to do too much and did not match our needs:
- Most of our API calls are sending JSON objects, as opposed to a series of parameters,
- Being able to query the real API is nice, but running anything but
GET
calls can get tricky ("What do you mean I deleted my stuff? I was just trying out the API calls!"), - Overall, setting up a separate server for what really requires a good static documentation seemed overkill.
The real value of Carte is its structure for describing APIs, not its underlying technical stack (or lack-thereof). In a nutshell; we built a static template for your API documentation, feel free to re-use it.
It' Jekyll god dammit:
- Clone this repository on your local,
- Install Jekyll,
- Go at the root of the repository and run
jekyll serve --watch
, - Go to http://localhost:4000,
- Great success! High five!
You can add a new API call by simply adding a new post in the _posts
folder. Jekyll by default forces you to specify a date in the file path: it makes us sad pandas too, but you'll have to stick to this format. You can use dates to control the order in which API calls are displayed in the interface.
Each API call can define a few values in its YAML header:
Variable | Mandatory | Default | Description |
---|---|---|---|
title |
Y | - | A short description of what that calls does. |
path |
N | - | The URL for the API call, including potential parameters. |
type |
N | - | Set it to PUT , GET , POST , DELETE or nothing (for parts of your documentation that do not relate to an actual API call). |
A typical header:
---
path: '/stuff/:id'
title: 'Delete a thing'
type: 'DELETE'
layout: nil
---
We then describe the request and response (or whatever else you wish to talk about) in the body of our post. Check the placeholders present in the _posts
folder to get an idea of what it can look like.
Adding a category to your YAML header will allows you to group methods in the navigation. It is particularly helpful as you start having a lot of methods and need to organize them. For example:
---
category: Stuff
path: '/stuff/:id'
title: 'Delete a thing'
type: 'DELETE'
layout: nil
---
The default UI is mostly described through the css/style.css
file and a couple short jQuery scripts in the /_layouts/default.html
layout. Hack it to oblivion.