web-dev-qa-db-fra.com

Méthodes standard pour documenter une API RESTful

J'écris une spécification pour une API RESTful pour un nouveau service Web interne. Ce n'est pas extrêmement long et assez simple, mais malgré tout, c'est la première fois que j'utilise strict REST (par opposition à la triche pour des raisons pratiques - en évitant PUT et DELETE parce qu'ils sont un problème en PHP, etc.). Je me demandais s'il y avait des méthodes standard ou des meilleures pratiques pour documenter une interface REST? Je veux que le reste de l'équipe comprendre en un coup d'œil, et pour quiconque veut écrire un client pour pouvoir le faire sans comprendre le code sous-jacent.

restdocumentation
65
Samir Talwar

Dans le post de Roy ici il déclare

Une API REST doit consacrer presque tout son effort descriptif à définir le ou les types de support utilisés pour représenter les ressources et piloter l'état de l'application, ou pour définir des noms de relation étendus et/ou une marque activée par hypertexte -up pour les types de supports standard existants. Tout effort consacré à décrire les méthodes à utiliser sur les URI d'intérêt devrait être entièrement défini dans le cadre des règles de traitement pour un type de support (et, dans la plupart des cas, déjà défini par les types de support existants) .

9
Darrel Miller

Bien sûr, les API REST devraient idéalement utiliser HATEOAS et être basées sur l'hypertexte (avec une utilisation intensive des types de médias), mais il est également utile de disposer d'une documentation simple et conviviale pour les développeurs.

Quelques outils spécifiques utiles pour générer de la documentation comme celle-ci:

  • Swagger
    • Une spécification ouverte pour décrire REST [ github ]
    • Outils de génération automatique
      • Documentation
      • Code pour votre API
    • Don à l'initiative OpenAPI et renommé OpenAPI en 2015
  • Mashery
    • Un projet open source [ github ]
    • Outils pour générer
      • Documentation
      • Une interface d'exploration pour votre API
  • Apiary and API Blueprint
    • Écrire la description de l'API dans une DSL dans le démarque
    • Outils de génération automatique
      • Documentation
      • Serveur simulé
    • Semble se concentrer sur les développeurs Ruby + mac
  • RAML
    • Une spécification pour décrire REST [ github ]
  • WADL
  • APIgee
    • Un produit commercial avec quelques fonctionnalités de documentation
  • échelles
    • Un produit commercial avec quelques fonctionnalités de documentation
  • miredot
    • Commercial REST Générateur de documentation API
    • Spécifique à Java
47
turtlemonvh

J'utilise http://apiary.io , ce qui est plutôt sympa. Vous pouvez également exporter la documentation de l'API vers github.

13
Martin Konecny

Une bonne documentation ReST signifierait documenter votre type de support et uniquement votre type de support.

Dans un scénario typique, vous produisez un document comme ceci:

Les formats XML Acme Corp

Découverte de lien

Les liens vers diverses ressources sont décrits dans un document qui peut être trouvé en émettant une requête GET ou HEAD au serveur sur un URI de signet (généralement la racine du serveur, http: //www.acme.org ), et à la recherche d'un en-tête de lien HTTP:

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

où la partie rel est la relation de liaison et la xxx est l'URI pour lequel la relation a été établie.

Relier les relations

Ce document définit les noms de relation suivants:

Types de supports

Le application/vnd.acme.services+xml est un document avec une sérialisation xml qui décrit une liste de liens qu'une application peut vouloir traiter.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

Le applcation/vnd.acme.customers+xml est un document avec une sérialisation xml qui décrit les clients.

Exemples de documents:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

etc...

Il s'agit de donner au développeur un moyen de suivre les liens que vous définissez. Trouvez d'abord le lien vers l'index afin qu'ils puissent obtenir la liste des éléments sur lesquels ils peuvent naviguer.

Une fois qu'ils ont découvert ce document, ils découvrent qu'ils peuvent voir une liste de clients à un certain Uri et peuvent faire un GET contre lui.

S'ils trouvent un client d'intérêt, ils peuvent suivre le lien défini dans /customers/customer/@href et émettez un GET pour récupérer une représentation de ce client.

À partir de là, votre type de média pourrait incorporer des actions disponibles pour l'utilisateur, en utilisant plus de liens. Vous avez également la possibilité supplémentaire d'émettre une demande OPTIONS sur la ressource pour savoir si vous pouvez autoriser la suppression de la ressource, ou un PUT si vous pouvez sauvegarder le document après modification.

Donc une bonne documentation ne fait jamais:

  • donner des liens statiques
  • donner une interaction telle que "vous pouvez émettre POST sur le client avec ce type de média et cela signifiera l'opération de déplacement". Le client doit émettre un POST contre le client uniquement parce que votre document XML l'a spécifié de cette façon.

Le but de tout cela est de réaliser un couplage minimum entre les clients et les serveurs. Le client peut être très intelligent pour afficher et découvrir des ressources (montrer des formulaires et Dieu sait quoi d'autre), mais il est totalement stupide quant à ce qu'est le flux de travail réel: le serveur décide.

6
SerialSeb

Dans mon entreprise, nous avons été très heureux d'utiliser WADL , Web Application Description Language. Wikipedia décrit comme: "un format de fichier basé sur XML qui fournit une description lisible par machine des applications Web basées sur HTTP". Je trouve que le WADL brut est facile à écrire, à lire et à comprendre, et il correspond directement aux concepts RESTful. Le projet officiel fournit une spécification simple, XSD et RELAX NG schemata, et Java tools.

Il existe un certain nombre d'outils et de ressources pour travailler avec WADL, notamment:

  • wadl_stylesheets , feuilles de style XSLT pour créer une documentation HTML à partir de fichiers WADL
  • Restlet , un Java pour la construction de serveurs et de clients RESTful, comprend une extension WADL

Un conseil: essayez d'inclure une documentation lisible par l'homme, comme les descriptions, les concepts, le démarrage, les conseils d'utilisation, etc., dans l'élément doc du document WADL en incluant des éléments HTML, en utilisant l'espace de noms XHTML. Cela peut faire une grande différence!

4
Avi Flax

Au départ, nous avons opté pour une documentation statique des ressources mais nous devions simplement répondre à trop de questions. Finalement, nous sommes passés à l'utilisation des pages de documentation Live en utilisant IO/Docs (en fait un fork ). Fonctionne très bien.

2
Raghu

Vous pourriez trouver rest-tool utile.

Il suit une approche indépendante du langage pour écrire des spécifications, une simulation d'implémentation et des tests unitaires automatisés pour les API RESTful. Il fournit également un livre de cuisine, mais il est à un stade très précoce, mais son contenu ne cesse de croître.

Les services que vous venez de décrire peuvent être immédiatement utilisés, ils sont donc également utiles pour l'expérimentation.

2
tombenke

Pour créer une compréhension/documentation, les solutions lourdes ne sont pas toujours nécessaires. Des exemples de (grands) outils lourds sont: IO/Docs/Apigee (bien que de grands outils).

Pour les petits projets qui ont déjà une configuration Docchain (doxygen/phpdoc/phpdoctor/custom/etc), j'utilise le shellscript suivant pour simplement inclure la page dans la documentation complète générée:

https://Gist.github.com/4496972

Une démo: http://pastie.org/565719

Il suffit d'utiliser des balises de commentaire personnalisées dans votre code source. Il peut également être un bon point de départ pour documenter n'importe quel code source (langue).

0
coderofsalvation