una standard restful generar ejemplo documentar documentacion como rest documentation

standard - Métodos estándar para documentar una API RESTful



standard api restful (8)

Estoy escribiendo una especificación para una API RESTful para un nuevo servicio web interno. No es demasiado largo y bastante simple, pero aún así, es la primera vez que uso un REST estricto (en lugar de hacer trampa por razones prácticas, evitando PUT y DELETE porque son un problema en PHP, etc.). Me preguntaba si había algún método estándar o mejores prácticas para documentar una interfaz REST. Quiero que el resto del equipo lo entienda de un vistazo, y para cualquiera que quiera escribir un cliente para poder hacerlo sin entender el código subyacente.

En la publicación de Roy here él dice

Una API REST debería dedicar casi todo su esfuerzo descriptivo a definir los tipos de medios utilizados para representar los recursos y dirigir el estado de las aplicaciones, o al definir nombres de relaciones extendidas y / o márgenes habilitados para hipertexto para los tipos de medios estándar existentes. Cualquier esfuerzo dedicado describiendo qué métodos usar en qué URI de interés debería estar completamente definido dentro del alcance de las reglas de procesamiento para un tipo de medio (y, en la mayoría de los casos, ya definido por los tipos de medios existentes).

En mi compañía, nos sentimos muy felices de usar WADL , Lenguaje de descripción de aplicaciones web. Wikipedia lo describes como: "un formato de archivo basado en XML que proporciona una descripción legible por máquina de aplicaciones web basadas en HTTP". Encuentro que WADL sin procesar es fácil de escribir, leer y comprender, y se correlaciona directamente con los conceptos RESTful. El proyecto oficial proporciona una especificación simple, esquemas XSD y RELAX NG y herramientas de Java.

Existen varias herramientas y recursos para trabajar con WADL, que incluyen:

  • wadl_stylesheets , hojas de estilo XSLT para crear documentación HTML a partir de archivos WADL
  • Restlet , un framework de Java para construir servidores y clientes RESTful, incluye una extensión WADL

Un consejo: trate de incluir documentación legible por humanos, como descripciones, conceptos, inicio, consejos de uso, etc., en el elemento doc del documento WADL incluyendo elementos HTML, usando el espacio de nombres XHTML. ¡Puede hacer una gran diferencia!

He estado usando http://apiary.io , lo cual es bastante bueno. También puede exportar la documentación API a github.

Inicialmente, buscamos documentación estática de los recursos, pero tuvimos que responder muchas preguntas. Eventualmente, pasamos a usar páginas de documentación en vivo usando IO / Docs (en realidad un fork ). He estado trabajando genial

Para crear comprensión / documentación, las soluciones de peso pesado no siempre son necesarias. Ejemplos de (grandes) herramientas pesadas son: IO / Docs / Apigee (aunque son excelentes herramientas).

Para proyectos pequeños que ya tienen una configuración de docchain (doxygen / phpdoc / phpdoctor / custom / etc) utilizo el siguiente shellscript para simplemente incluir la página en la documentación generada completa:

https://gist.github.com/4496972

Una demostración: http://pastie.org/5657190

Simplemente usa etiquetas de comentarios personalizadas en tu código fuente. También puede ser un buen punto de partida para documentar cualquier código fuente (lenguaje).

Por supuesto, las API REST deberían usar HATEOAS idealmente y estar basadas en hipertexto (con un uso intensivo de los tipos de medios), pero también es útil tener una documentación simple y amigable para los desarrolladores.

Algunas herramientas específicas que son útiles para generar documentación como esta:

  • Swagger
    • Una especificación abierta para describir las API REST [ github ]
    • Herramientas para la autogeneración
      • Documentación
      • Código para su API
    • Donado a la iniciativa OpenAPI y renombrado OpenAPI en 2015
  • Mashery
    • Un proyecto de código abierto [ github ]
    • Herramientas para generar
      • Documentación
      • Una interfaz de exploración para su API
  • Apiary y API Blueprint
    • Escriba la descripción de la API en una DSL dentro de la marca
    • Herramientas para la autogeneración
      • Documentación
      • Servidor simulado
    • Parece estar enfocado en ruby ​​+ mac devs
  • RAML
    • Una especificación para describir las API REST [ github ]
  • WADL
    • Una especificación para escribir documentos de API detectables con XML
    • Algunos debates que comparan WSDL y WADL
  • APIgee
    • Un producto comercial con algunas características de documentación
  • 3scale
    • Un producto comercial con algunas características de documentación
  • miredot
    • Generador de documentación REST API comercial
    • Específico de Java

Puede encontrar rest-tool útil.

Sigue un enfoque independiente del idioma para escribir especificaciones, simulacros de implementación y pruebas unitarias automatizadas para API RESTful. También proporciona un libro de cocina, pero está en una etapa muy temprana, pero su contenido está en continuo crecimiento.

Los servicios que acaba de describir se pueden usar inmediatamente, por lo que también es bueno para experimentar.

Una buena documentación ReST significaría documentar su tipo de medio y solo su tipo de medio.

En un escenario típico, producirías un documento como ese:

Los formatos XML de Acme Corp

Link Discovery

Los enlaces a varios recursos se describen en un documento que se puede encontrar al emitir una solicitud GET o HEAD al servidor en un URI de marcador (generalmente la raíz del servidor, http://www.acme.org ), y buscar un Encabezado de enlace HTTP:

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

donde la parte rel es la relación de enlace, y xxx es el URI para el que se ha establecido la relación.

Relaciones de enlace

Este documento define los siguientes nombres de relación:

Tipos de medios

La application/vnd.acme.services+xml es un documento con una serialización xml que describe una lista de enlaces que una aplicación puede querer procesar.

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

La applcation/vnd.acme.customers+xml es un documento con una serialización xml que describe a los clientes.

Documentos de ejemplo:

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

etc ...

El objetivo es dar al desarrollador la posibilidad de seguir los enlaces que defina. Primero encuentre el enlace al índice para que puedan obtener la lista de cosas a las que pueden acceder.

Una vez que descubren ese documento, descubren que pueden ver una lista de clientes en un Uri determinado y pueden hacer un GET contra.

Si encuentran un cliente de interés, pueden seguir el enlace definido en /customers/customer/@href y emitir un GET para recuperar una representación de ese cliente.

A partir de ahí, su tipo de medio puede incrustar acciones que están disponibles para el usuario, utilizando más enlaces. También tiene la opción adicional de emitir una solicitud de OPCIONES en el recurso para saber si puede permitir la eliminación del recurso, o un PUT si puede guardar el documento nuevamente después de la modificación.

Entonces, una buena documentación nunca:

  • dar enlaces estáticos
  • brinde interacción tal como "puede emitir POST en el Cliente con este tipo de medio y eso significará la operación de movimiento". El cliente debe emitir un POST contra el Cliente solo porque su documento XML lo ha especificado de esa manera.

El objetivo de todo esto es lograr un acoplamiento mínimo entre clientes y servidores. El cliente puede ser muy inteligente al mostrar y descubrir recursos (mostrando formularios y sabe Dios qué más), pero es totalmente tonto en cuanto a cuál es el flujo de trabajo real: el servidor decide.