jak wygenerować dokumentację api

Question

Potrzebuję napisać dokumentację API dla utworzonego przeze mnie interfejsu REST API. Czy są jakieś narzędzia, które wydrążą ładną treść HTML podobną w stylu do dokumentacji z dodatkowym interfejsem API? A może coś, co będzie produkować coś jak twitter bootstrap w stylu html?

Widzę, że docco robi nienormowany kod, ale ja właściwie chcę tylko udokumentować API. Idealnie chciałbym wskazać narzędzie w pliku kontrolera i wygenerować dokumentację na temat metod i tras, ale nie pokazać żadnego kodu źródłowego, chyba że konkretnie wyślę przykłady.

Answer 1

apiDoc tworzy dokumentację z adnotacji API w kodzie źródłowym.

Integrated to historia interfejsu API, dzięki której można porównywać różne poziomy wersji interfejsu API. Tak więc można go odtworzyć, co zmieniło się w API od czasu ostatniej wersji.

Demo: http://apidocjs.com/example

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

Answer 2

Zapoznaj się z dokumentami I/O na Github - http://github.com/mashery/iodocs. Został zhakowany w Node.js i ma duży wkład/zaangażowanie społeczności. Aby zobaczyć to działa w środowisku naturalnym:

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

Uber schematu prosta konfiguracja (JSON), i piekło, jeśli nie chcesz, aby opisać to wszystko ręcznie w JSON należy użyć I/o lekarz, internetowe narzędzie do importowania/budowania configs JSON z Ui:

• http://iodoctor.net/

Również dostępne na Github na https://github.com/brandonmwest/iodoctor

Daj mi znać, jeśli mogę pomóc Ci zacząć. Istnieje wiele przykładowych konfiguracji w repozytorium dokumentów I/O. Dbać.

Answer 3

Dokumenty I/O lub Swagger, które są najpopularniejszym systemem dokumentacji RESTful API. Istnieje również RAML i Apiary.

Answer 4

test2doc.js pozwala na generowanie dokumentacji API od testów/specyfikacji. Dzięki temu zawsze możesz uzyskać najnowsze zaktualizowane dokumenty API wypełnione prawdziwymi danymi dotyczącymi żądań/odpowiedzi.

test przykładowy kod:

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