web-dev-qa-db-fra.com

comment générer de la documentation api

J'ai besoin d'écrire de la documentation api pour une API REST que j'ai créée. Existe-t-il des outils qui stubent une sortie html Nice de style similaire à la documentation api de soulignement? Ou peut-être quelque chose qui affichera quelque chose sous forme de Twitter bootstrap style html?

Je vois que docco fait du code annoé, mais je cherche juste à documenter l'API uniquement. Idéalement, je voudrais pointer un outil vers le fichier du contrôleur et lui faire générer de la documentation sur les méthodes et les itinéraires, mais ne montrer aucun code source, sauf si j'appelle spécifiquement des exemples.

node.jsdocumentationtwitter-bootstrapdocumentation-generation
31
MonkeyBonkey

apiDoc crée une documentation à partir d'annotations API dans votre code source.

Intégré est un historique d'API, avec lequel différents niveaux de version d'API peuvent être comparés. Il est donc possible de retracer ce qui a changé dans l'API depuis la dernière version.

Démo: http://apidocjs.com/example

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

39
Diogo Cardoso

Consultez les documents d'E/S sur Github - http://github.com/mashery/iodocs . Il est piraté dans Node.js et a beaucoup de contribution/implication de la communauté. Pour le voir fonctionner à l'état sauvage:

Schéma de configuration simple Uber (JSON), et diable, si vous ne voulez pas tout décrire à la main dans JSON, utilisez I/O Doctor, un outil Web pour importer/construire des configurations JSON avec une interface utilisateur:

Également disponible sur Github à https://github.com/brandonmwest/iodoctor

Faites-moi savoir si je peux vous aider à démarrer. Il existe de nombreux exemples de configurations dans le référentiel I/O Docs. Prends soin de toi.

13
mansilladev

I/O Docs ou Swagger, qui sont les systèmes de documentation d'API RESTful les plus populaires. Il y a aussi RAML et Apiary .

6
theofpa

test2doc.js vous aide à générer de la documentation API à partir de vos tests/spécifications. Ainsi, vous pouvez toujours obtenir les derniers documents API actualisés à jour, remplis de données de demande/réponse réelles.

Exemple de code de test:

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