Как создать документацию api

Мне нужно написать некоторую документацию api для REST API, который я создал. Есть ли инструменты, которые будут вырезать хороший html-вывод, похожий по стилю, на документацию подписи underscore? Или, может быть, что-то, что выведет что-то в качестве twitter bootstrap в стиле html?

Я вижу, что docco делает аннотированный код, но на самом деле я просто хочу документировать только API. В идеале я хотел бы указать инструмент в файле контроллера и создать документацию о методах и маршрутах, но не показывать какой-либо исходный код, если я специально не приведу примеры.

Ответы

Ответ 1

apiDoc создает документацию из аннотаций API в исходном коде.

Интегрированная история API, с которой можно сравнивать различные уровни версий API. Таким образом, он может быть восстановлен, что изменилось в API с последней версии.

Демо: http://apidocjs.com/example

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

Ответ 2

Проверьте документы ввода-вывода в Github - http://github.com/mashery/iodocs. Он взломан в Node.js и имеет много вклада/участия сообщества. Чтобы увидеть, как он работает в дикой природе:

простая схема конфигурации Uber (JSON), и, черт возьми, если вы не хотите все это описывать вручную в JSON, используйте I/O Doctor, веб-инструмент для импорта/создания конфигураций JSON с пользовательским интерфейсом:

Также доступен на Github в https://github.com/brandonmwest/iodoctor

Сообщите мне, смогу ли я помочь вам начать работу. В репозитории Документов ввода-вывода имеется множество примеров конфигураций. Будьте осторожны.

Ответ 3

Документы ввода/вывода или Swagger, которые являются наиболее популярными системами документации API RESTful. Существует также RAML и Apiary.

Ответ 4

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