Necesito escribir la documentación de un servicio RESTful. ¿Alguien sabe de una documentación muy bien escrita para un servicio RESTful que podría usar como plantilla para mí?Ejemplo de un servicio RESTful bien documentado
Gracias.
La Twitter Api documentation es la mejor que he encontrado.
Los documentos de la API de Twitter han cambiado - [https://dev.twitter.com/rest/public](https://dev.twitter.com/ resto/público) – GuirNab
El Readability API ha sido alabado recientemente en Twitter.
Divulgación: Parter en Arc90, los creadores de legibilidad, y un inversor en legibilidad.
El API of CouchDB, "la" base de datos RESTful.
Observará que el documento está estructurado por recurso en lugar de por método, lo que lo hace más orientado a recursos que la mayoría de las documentaciones de API conocidas.
Probar rest-tool.
Sigue un enfoque independiente del idioma para escribir la especificación. Proporciona implementación simulada instantánea y pruebas unitarias automatizadas para API RESTful de forma gratuita.
Los servicios se especifican mediante archivos YAML y los datos de muestra se pueden colocar justo al lado de los descriptores. Puede encontrar un esquema JSON sobre el formato del archivo descriptor service.yml. Esto se puede usar como guilde, pero es extensible a pedido.
Puede consultar Zoho Subscriptions API Documentación. Este documento de diseño de 3 columnas está estructurado por recursos y tiene una solicitud de muestra y respuesta para cada punto final.
Divulgación: Soy parte del equipo de suscripciones de Zoho.
¿Cómo puedo escribir uno así? ¿Usaste alguna herramienta para eso? Por favor sugiérame, estoy en camino de construir nuestra documentación API. – theGamblerRises
¿Has oído hablar sobre http://swagger.io/? Genera una documentación muy útil (y agradable) para una API REST.
Pruébalo. Realmente lo recomiendo
Consulte la documentación de REST API Documentation Best Practices para documentar su servicio RESTful. El documento cubre todos los aspectos. Aquí hay un fragmento de esto.
Título: Mostrar todos los usuarios.
URL:/o usuarios/usuarios/Identificación: o/usuarios de id =: Identificación del
Método:? GET | POST | ELIMINAR | PONER
URL Parámetros:Required:id = [número entero] OOptional:photo_id = [alfanumérico]
de datos Parámetros: {u: {correo electrónico: [cadena], nombre: [cadena], current_password: [alfanumérico] contraseña : [alfanumérico], password_confirmation: []}} alfanumérica
Códigos de respuesta: éxito (200 OK), Bad Request (400), no autorizados (401)
¿cuál es la diferencia entre los tipos de datos "cadena" y "alfanumérico"? – mre
¿le ha resultado uno? Me interesa saber cuál si lo hiciste. –
Un servicio RESTful no necesita una documentación escrita muy buena. :) –
Cada API necesita una buena documentación bien escrita – kralco626