Structuration de la documentation en ligne pour une API REST
Je construis ma première API Reste qui sérialise les données aux formats JSON et XML. J'aimerais fournir une page d'index aux clients API, où ils pourraient choisir des points de terminaison implémentés.
Quelles informations dois-je inclure pour rendre mon API plus utile et comment dois-je l'organiser?
C'est une question très complexe pour une réponse simple.
Vous voudrez peut-être jeter un coup d'œil aux frameworks d'API existants, tels que Swagger Spécification ( OpenAPI ), et à des services tels que apiary.io et apiblueprint.org .
En outre, voici un exemple de la même REST API 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 communes existantes.
- https://api.coinsecure.in/v1
- https://api.coinsecure.in/v1/originalUI
- https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid
Au plus haut niveau, je pense que la qualité REST la documentation de l'API requiert au moins les éléments suivants:
- une liste de tous vos points de terminaison API (URL de base/relatives)
- type de méthode HTTP GET/POST/... correspondant à chaque noeud final
- type MIME de demande/réponse (comment coder les paramètres et analyser les réponses)
- un exemple de demande/réponse, y compris les en-têtes HTTP
- type et format spécifié 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 extrait de code indiquant l'utilisation du terminal 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 d'API ou votre schéma et générer un ensemble pratique de documents pour vous. Mais le choix d'un système de génération de documentation dépend de votre projet, de la langue, de l'environnement de développement et de bien d'autres choses.