web-dev-qa-db-ja.com

APIドキュメントを生成する方法

REST私が作成したAPIのAPIドキュメントを書く必要があります。アンダースコアAPIドキュメントに似たスタイルのNice html出力をスタブするツールはありますか？ Twitter bootstrap styled html？

Doccoは注釈付きのコードを実行するようですが、実際にはAPIのみを文書化することを検討しています。理想的には、コントローラーファイルにツールを向けて、メソッドとルートに関するドキュメントを生成するようにしますが、特に例を呼び出さない限り、ソースコードは表示しません。

node.jsdocumentationtwitter-bootstrapdocumentation-generation
31
MonkeyBonkey

apiDoc は、ソースコード内のAPIアノテーションからドキュメントを作成します。

統合はAPI履歴であり、さまざまなAPIバージョンレベルを比較できます。したがって、前回のバージョン以降にAPIで何が変更されたかを追跡できます。

デモ： http://apidocjs.com/example

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

39
Diogo Cardoso

GithubでI/Oドキュメントを確認してください- http://github.com/mashery/iodocs Node.jsでハッキングされており、多くのコミュニティの貢献/関与があります。実際に動作することを確認するには：

Uber Simple Configuration Schema（JSON）、そして地獄、JSONですべてを手動で記述したくない場合、UIでJSON構成をインポート/構築するためのWebベースのツールであるI/O Doctorを使用します：

Githubの https://github.com/brandonmwest/iodoctor でも入手可能

あなたが始めるのを助けることができるかどうか私に知らせてください。 I/O Docsリポジトリには多くの設定例があります。気を付けて。

13
mansilladev

I/O DocsまたはSwagger。最も人気のあるRESTful APIドキュメントシステムです。 [〜＃〜] raml [〜＃〜] および Apiary もあります。

6
theofpa

test2doc.js は、テスト/仕様からAPIドキュメントを生成するのに役立ちます。そのため、実際の要求/応答データが入力された最新の更新APIドキュメントをいつでも入手できます。

テストコードの例：

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