SLATE est un générateur de documentation API gratuit et open source. Les sources du projet peuvent être récupérées ici.
Basé sur le langage RUBY, la description de la documentation se fait via le langage MARKDOWN, langage de « simplification » du langage HTML.
SLATE permet donc de faciliter la création d’un portail documentaire d’API au design « responsive » et intuitif.
1 – Description graphique
Par défaut, le « template » source se compose en 3 zones :
- Un premier bandeau latéral gauche de « menu » (1)
- Un espace central pour les descriptifs en textes et tableaux (2)
- Un second bandeau latéral droit pour la correspondance technique de la ressource API décrite (3)
La zone 3 se compose d’un espace pour la requête et un autre pour la réponse.
L’espace pour la requête a l’avantage de pouvoir proposer une navigation par onglets des descriptions de différents langages d’une ressource API donnée avec une coloration syntaxique prédéfinie du langage choisi.
Le projet couvre plus d’une centaine de langages sans aucune configuration particulière requise au-delà de la nomination du langage choisi.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
# Kittens ## Get All Kittens ```ruby require 'kittn' api = Kittn::APIClient.authorize!('meowmeowmeow') api.kittens.get ``` ```python import kittn api = kittn.authorize('meowmeowmeow') api.kittens.get() ``` ```shell curl "http://example.com/api/kittens" -H "Authorization: meowmeowmeow" ``` ```javascript const kittn = require('kittn'); let api = kittn.authorize('meowmeowmeow'); let kittens = api.kittens.get(); ``` > The above command returns JSON structured like this: ```json [ { "id": 1, "name": "Fluffums", "breed": "calico", "fluffiness": 6, "cuteness": 7 }, { "id": 2, "name": "Max", "breed": "unknown", "fluffiness": 5, "cuteness": 10 } ] ``` |
2 – Description technique
Une fois le projet « git » récupéré sur un serveur local (Linux ou macOS), il suffit de lancer les commandes suivantes pour lancer l’installation puis la compilation des sources et le déploiement du portail :
|
1 |
$ bundle install |
|
1 2 3 4 5 |
$ bundle exec middleman server Expected string default value for '--instrument'; got false (boolean) == The Middleman is loading == View your site at "http://localhost:4567", "http://127.0.0.1:4567" == Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman" |
Le portail est alors accessible via l’URL suivante : http://localhost:4567
Le répertoire des sources se compose d’une arborescence de dossiers, simple et intelligible, avec comme fichier « maître » un fichier « index.html.md » :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
--- title: API Reference language_tabs: # must be one of https://git.io/vQNgJ - shell - ruby - python - javascript toc_footers: - <a href='#'>Sign Up for a Developer Key</a> - <a href='https://github.com/lord/slate'>Documentation Powered by Slate</a> includes: - errors search: true --- # Introduction Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database. We have language bindings in Shell, Ruby, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. This example API documentation page was created with [Slate](https://github.com/lord/slate). Feel free to edit it and use it as a base for your own API's documentation. ... |
Quand le portail est déployé, toute modification des sources est auto-compilée avec traces en cas d’erreurs affichées dans le terminal.
Quelques sociétés utilisant SLATE :
