cómo generar la documentación de API

Question

Necesito escribir alguna documentación de API para una API de REST que he creado. ¿Hay herramientas que resuelvan un buen resultado html similar en estilo a la documentación de la API de subrayado? ¿O tal vez algo que genere algo como un booteo de Twitter estilo html?

Veo que docco hace un código anotado, pero en realidad solo estoy buscando documentar la API solamente. Idealmente, me gustaría señalar una herramienta en el archivo del controlador y hacer que genere documentación sobre los métodos y rutas, pero no mostrar ningún código fuente a menos que específicamente llame ejemplos.

Answer 1

apiDoc crea una documentación a partir de anotaciones API en su código fuente.

Integrado es un historial de API, con el que se pueden comparar varios niveles de versión de API. Por lo tanto, se puede volver sobre lo que cambió en la API desde la última versión.

Demostración: http://apidocjs.com/example

Github: https://github.com/apidoc/apidoc

Answer 2

Consulte los documentos de E/S en Github - http://github.com/mashery/iodocs. Ha sido pirateado en Node.js, y tiene mucha contribución/participación de la comunidad. Para ver su funcionamiento en la naturaleza:

• http://iodocs.docusign.com
• http://console.datasift.com/datasift

Uber esquema de configuración sencilla (JSON), y el infierno, si no se quiere describir todo a mano en JSON , utilice E/S doctor, una herramienta basada en la web para la importación/construcción de configuraciones JSON con una interfaz de usuario:

• http://iodoctor.net/

También disponible en Github en https://github.com/brandonmwest/iodoctor

Avísame si puedo ayudarle a empezar. Hay muchas configuraciones de ejemplo en el repositorio de I/O Docs. Cuídate.

Answer 3

I/O Docs o Swagger, que son los sistemas de documentación de API RESTful más populares. También hay RAML y Apiary.

Answer 4

test2doc.js le ayuda a generar documentación de la API de sus pruebas/especificaciones. Por lo tanto, siempre puede obtener los últimos documentos API actualizados hasta la fecha, rellenos con datos reales de solicitud/respuesta.

Prueba de código de ejemplo:

const doc = require('test2doc') 
const request = require('supertest') // We use supertest as the HTTP request library 
require('should') // and use should as the assertion library 

// For Koa, you should exports app.listen() or app.callback() in your app entry 
const app = require('./my-express-app.js') 

after(function() { 
    doc.emit('api-documentation.apib') 
}) 

doc.group('Products').is(doc => { 
    describe('#Products', function() { 
    doc.action('Get all products').is(doc => { 
     it('should get all products', function() { 
     // Write specs towards your API endpoint as you would normally do 
     // Just decorate with some utility methods 
     return request(app) 
      .get(doc.get('/products')) 
      .query(doc.query({ 
      minPrice: doc.val(10, 'Only products of which price >= this value should be returned') 
      })) 
      .expect(200) 
      .then(res => { 
      body = doc.resBody(res.body) 
      body.desc('List of all products') 
       .should.not.be.empty() 
      body[0].should.have.properties('id', 'name', 'price') 
      body[0].price.desc('Price of this product').should.be.a.Number 
      }) 
     }) 
    }) 
    }) 
})