Wie api-Dokumentation zu generieren

Question

Ich muss einige API-Dokumentation für eine REST-API schreiben, die ich erstellt habe. Gibt es Werkzeuge, die eine nette HTML-Ausgabe ausgeben, ähnlich wie die Unterstrich-API-Dokumentation? Oder vielleicht etwas, das etwas als Twitter-Bootstrap-formatiertes HTML ausgeben wird?

Ich sehe, dass Docco annoated Code, aber ich bin eigentlich nur auf der Suche nach der API nur zu dokumentieren. Idealerweise würde ich gerne ein Werkzeug auf die Controller-Datei zeigen und es würde eine Dokumentation über die Methoden und Routen erzeugen, aber keinen Quellcode anzeigen, wenn ich nicht speziell Beispiele herausrufe.

Answer 1

erstellt eine Dokumentation aus API-Anmerkungen in Ihrem Quellcode.

Integriert ist eine API-Historie, mit der verschiedene API-Versionsstufen verglichen werden können. So kann nachvollzogen werden, was sich seit der letzten Version in der API geändert hat.

Demo: http://apidocjs.com/example

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

Answer 2

Auschecken I/O Docs auf Github - http://github.com/mashery/iodocs. Es ist in Node.js gehackt und hat viel Gemeinschaftsbeitrag/Beteiligung. Um zu sehen, sie in der freien Natur arbeiten:

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

Uber einfaches Konfigurationsschema (JSON), und die Hölle, wenn man nicht alles von Hand in JSON beschreiben will verwenden Sie E/a-Arzt, ein webbasiertes Tool für den Import/Aufbau JSON configs mit einer Benutzeroberfläche:

• http://iodoctor.net/

Auch auf Github bei https://github.com/brandonmwest/iodoctor

Lassen Sie mich wissen, wenn ich Ihnen den Einstieg erleichtern können. Im I/O Docs Repo gibt es viele Beispielkonfigurationen. Pass auf.

Answer 3

E/A Docs oder Swagger, die beliebtesten RESTful-API-Dokumentationssysteme. Es gibt auch RAML und Apiary.

Answer 4

test2doc.js hilft Ihnen, API-Dokumentation aus Ihren Tests/Spezifikationen erzeugen. So können Sie immer die aktuellsten API-Dokumente für die Aktualisierung erhalten, die mit echten Anfrage-/Antwortdaten gefüllt sind.

Prüfregeln Beispiel:

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