comment générer la documentation de l'api

J'ai besoin pour écrire la documentation de l'api pour une API REST que j'ai créé. Existe-il des outils qui permettront d'écraser une belle sortie html similaire dans le style de soulignement documentation de l'api? Ou peut-être quelque chose qui va de la sortie de quelque chose comme un twitter bootstrap de style html?

Je vois que docco ne annoated code, mais en fait, je suis simplement à la recherche de document de l'API uniquement. Idéalement, je voudrais souligner un outil au contrôleur de fichier et de générer de la documentation sur les méthodes et les itinéraires, mais de ne pas montrer tout le code source, à moins que j'ai spécifiquement appeler exemples.

  • J'aimerais vérifier comment Express.js génère la documentation. Il utilise une combinaison de nœud scripts, des scripts shell et dox.
InformationsquelleAutor MonkeyBonkey | 2012-08-15
  1. 39

    apiDoc crée une documentation de l'API annotations dans votre code source.

    Intégrée est une histoire de l'API, avec différentes version de l'API peuvent être comparés.
    De sorte qu'il peut être retracé ce qui a changé dans l'API depuis la dernière version.

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

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

    • Notez que cette bibliothèque n'est plus activement maintenu.
    • Est-il un moyen de créer l'inverse? c'est à dire de créer des API d'annotations à partir de la documentation.
    InformationsquelleAutor Diogo Cardoso
  2. 13

    Découvrez I/O Docs sur Github - http://github.com/mashery/iodocs . C'est piratés Node.js et a beaucoup de contribution de la communauté ou de participation. Le voir fonctionner dans la nature:

    Uber simple schéma de configuration (JSON), et de l'enfer, si vous ne voulez pas vous décrire tout à la main en JSON, utilisez I/O Médecin, un outil basé sur le web pour l'importation/bâtiment JSON configs avec une INTERFACE utilisateur:

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

    Laissez-moi savoir si je peux vous aider à obtenir commencé. Il existe de nombreux exemples de configs dans le I/O Docs repo. Prendre soin.

    • Est-il possible, que vous connaissez, pour générer Mashery I/O Docs de la .NET WebAPI ApiExplorer (de la même façon Swagger n')?
    • S'il vous plaît corriger les liens dans la réponse. Certains d'entre eux sont cassés.
    • Notez que cette bibliothèque n'est plus activement maintenu.
    InformationsquelleAutor mansilladev
  3. 6

    I/O Docs ou Swagger, qui sont les plus populaires API RESTful systèmes de documentation. Il est également RAML et Rucher.

    InformationsquelleAutor theofpa
  4. 2

    test2doc.js vous aide à générer de la documentation de l'API de vos tests/specs. De sorte que vous pouvez toujours avoir la dernière mise à jour de l'API de documents, peuplée avec de vraies données de requête/réponse.

    Code de Test exemple:

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