node.js - guide - node js server

como generar documentación de api

Question

Necesito escribir alguna documentación de la API para una API REST que he creado. ¿Existen herramientas que apaguen un buen resultado html similar en estilo a la documentación del subrayado de la API? ¿O tal vez algo que genere algo como un html de estilo bootstrap de twitter?

Veo que docco hace un código anónimo, pero en realidad solo estoy buscando documentar la API solamente. Lo ideal sería apuntar una herramienta al archivo del controlador y hacer que genere documentación sobre los métodos y las rutas, pero no muestre ningún código fuente a menos que mencione específicamente algunos ejemplos.

Answer 1

Echa un vistazo a los documentos de E / S en Github - http://github.com/mashery/iodocs . Se piratea en Node.js y tiene una gran cantidad de contribución / participación de la comunidad. Para verlo trabajando en la naturaleza:

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

Use el esquema de configuración simple (JSON) y, si no desea describirlo todo a mano en JSON, use I / O Doctor, una herramienta basada en web para importar / construir configuraciones JSON con una interfaz de usuario:

• http://iodoctor.net/

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

Déjame saber si puedo ayudarte a empezar. Hay muchas configuraciones de ejemplo en el repositorio de documentos de E / S. Cuídate.

Answer 2

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

Answer 3

apiDoc crea una documentación a partir de anotaciones de 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 rastrear lo que cambió en la API desde la última versión.

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

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

Answer 4

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

Ejemplo de código de prueba:

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
          })
      })
    })
  })
})