Structurer la documentation en ligne pour une API REST

85

Je construis ma première API Rest qui sérialise les données aux formats JSON et XML. Je voudrais fournir une page d'index aux clients API, où ils pourraient choisir les points de terminaison implémentés.

Quelles informations dois-je inclure pour rendre mon API plus utile, et comment dois-je l'organiser?

api rest indexing aumanets
la source

Réponses:

6

C'est une question très complexe pour une réponse simple.

Vous voudrez peut-être jeter un œil aux frameworks d'API existants, tels que Swagger Specification ( OpenAPI ), et des services tels que apiary.io et apiblueprint.org .

En outre, voici un exemple de la même API REST décrite, organisée et même stylisée de trois manières différentes. Ce peut être un bon début pour vous d'apprendre des méthodes courantes existantes.

Au plus haut niveau, je pense que les documents de qualité sur l'API REST nécessitent au moins les éléments suivants:

  • une liste de tous vos points de terminaison d'API (URL de base / relatives)
  • type de méthode HTTP GET / POST / ... correspondant pour chaque point de terminaison
  • requête / réponse de type MIME (comment encoder les paramètres et analyser les réponses)
  • un exemple de requête / réponse, y compris les en-têtes HTTP
  • type et format spécifiés pour tous les paramètres, y compris ceux de l'URL, du corps et des en-têtes
  • une brève description textuelle et des notes importantes
  • un court extrait de code montrant l'utilisation du point de terminaison dans les langages de programmation Web populaires

Il existe également de nombreux frameworks de documentation basés sur JSON / XML qui peuvent analyser votre définition ou schéma d'API et générer un ensemble pratique de documents pour vous. Mais le choix d'un système de génération de documents dépend de votre projet, de votre langage, de votre environnement de développement et bien d'autres choses.

Igor Kroitor
la source