Aller au contenu
  • Société
    • Qui sommes-nous
    • Nos valeurs
    • Nos partenaires
    • Entreprise citoyenne
    • Régions
  • Services
    • Expertise
    • Formation
    • Développement
    • Migration
    • Infogérance
  • Join the Team
  • Actualités
  • Blog
    • Blog easyteam.fr
    • Blog Cloud Natives
  • Formations
  • Rugb’Easyteam
  • Contact
Menu
  • Société
    • Qui sommes-nous
    • Nos valeurs
    • Nos partenaires
    • Entreprise citoyenne
    • Régions
  • Services
    • Expertise
    • Formation
    • Développement
    • Migration
    • Infogérance
  • Join the Team
  • Actualités
  • Blog
    • Blog easyteam.fr
    • Blog Cloud Natives
  • Formations
  • Rugb’Easyteam
  • Contact
Inscrivez-vous à la newsletter

Inscrivez-vous à la newsletter

Abonnez-vous maintenant et nous vous tiendrons au courant.
Nous respectons votre vie privée. Vous pouvez vous désabonner à tout moment.

Bienvenue sur le Blog d'EASYTEAM (ex ArKZoYd)

  • Accueil
  • Actualités
  • Cloud
  • Infrastructure
  • Données / Sécurité
  • Intégration
  • Dev / DevOps
  • SAM / FinOps
Menu
  • Accueil
  • Actualités
  • Cloud
  • Infrastructure
  • Données / Sécurité
  • Intégration
  • Dev / DevOps
  • SAM / FinOps
  • le 05/08/2019
  • ygamba
  • Intégration, SOA & Urbanisation

Un portail documentaire d’API avec SLATE

Partager sur linkedin
LinkedIn
Partager sur twitter
Twitter
Partager sur facebook
Facebook

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.

# 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 :

$ bundle install
$ 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 » :

---
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 :

  • NASA
  • Sony
  • PayPal

 

ygamba
ygamba
Voir tous ses articles
Partager sur linkedin
LinkedIn
Partager sur twitter
Twitter
Partager sur facebook
Facebook

1 réflexion sur “Un portail documentaire d’API avec SLATE”

  1. Ping : Master Note Middleware 2019 - EASYTEAM

Laisser un commentaire Annuler la réponse

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Les derniers articles

  • Customiser le monitoring des ressources Weblogic avec JMX 01/03/2021
  • Modernisation d’Oracle SOA Suite 22/02/2021
  • SQL Server 2019 : nouveauté TDE 15/02/2021
  • Libérer de l’espace sur les serveurs Oracle Weblogic 08/02/2021
  • Perdre Un Nœud d’un Cluster Always On 01/02/2021

Les derniers commentaires

  • PEDRO dans Contention du listener : Comment désactiver la notification ?
  • SY dans Oracle Database 12c In-Memory: Configuration/Découverte de l’option
  • Jeancy dans Configurer la messagerie de l’Agent SQL Server en vue de l’utilisation de la messagerie de base de données
  • Libérer de l'espace sur les serveurs Oracle Weblogic - EASYTEAM dans "Dans le doute, reboot !" et si on rendait cela scriptable et modulable !
  • Arnaud dans OCI Designer Toolkit : Créer, visualiser et déployer vos environnements OCI graphiquement
Espace Membres
Mot de passe perdu ?
EASYTEAM

Tour Nova, 71 Boulevard National,
92250 La Garenne-Colombes
Tél. 0800 40 60 40
contact@easyteam.fr

Facebook
Linkedin
Twitter
Navigation
  • Accueil
  • Qui sommes-nous
  • Entreprise citoyenne
  • Nos valeurs
  • Régions
  • Partenaires
  • Contact
  • Support
Menu
  • Accueil
  • Qui sommes-nous
  • Entreprise citoyenne
  • Nos valeurs
  • Régions
  • Partenaires
  • Contact
  • Support
Services
  • Développement
  • Migration
  • Infogérance
  • Expertise
  • Formation
Menu
  • Développement
  • Migration
  • Infogérance
  • Expertise
  • Formation
Blog
  • Cloud
  • Infrastructures
  • Data
  • Intégration
  • Dev / DevOps
  • SAM / FinOps
  • Applications
Menu
  • Cloud
  • Infrastructures
  • Data
  • Intégration
  • Dev / DevOps
  • SAM / FinOps
  • Applications
Copyright 2018 - EASYTEAM, Tous droits réservés
Mentions légales
Politique de confidentialité​