cách tạo tài liệu api

Question

Tôi cần viết một số tài liệu api cho API REST mà tôi đã tạo. Có công cụ nào sẽ tạo ra một đầu ra html tốt đẹp tương tự trong phong cách cho tài liệu hướng dẫn api dưới đây không? Hoặc có lẽ một cái gì đó mà sẽ sản xuất một cái gì đó như là một html theo kiểu bootstrap twitter?

Tôi thấy rằng docco đã hủy mã, nhưng tôi thực sự chỉ đang tìm cách ghi lại tài liệu API. Lý tưởng nhất là tôi muốn trỏ một công cụ vào tập tin điều khiển và nó tạo ra tài liệu về các phương thức và các tuyến nhưng không hiển thị bất kỳ mã nguồn nào trừ khi tôi đặc biệt gọi ra các ví dụ.

Answer 1

apiDoc tạo tài liệu từ chú thích API trong mã nguồn của bạn.

Tích hợp là lịch sử API, với các cấp phiên bản API khác nhau có thể được so sánh. Vì vậy, nó có thể được retraced những gì thay đổi trong API kể từ phiên bản cuối cùng.

Demo: http://apidocjs.com/example

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

Answer 2

Kiểm tra tài liệu I/O trên Github - http://github.com/mashery/iodocs. Nó bị tấn công trong Node.js và có rất nhiều đóng góp/sự tham gia của cộng đồng. Để xem nó làm việc trong môi trường tự nhiên:

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

Uber schema cấu hình đơn giản (JSON), và địa ngục, nếu bạn không muốn để mô tả nó tất cả bằng tay trong JSON , sử dụng I/O Doctor, một công cụ dựa trên web cho nhập khẩu/xây dựng configs JSON với một giao diện người dùng:

• http://iodoctor.net/

Cũng có sẵn trên Github tại https://github.com/brandonmwest/iodoctor

Hãy cho tôi biết nếu tôi có thể giúp bạn bắt đầu. Có rất nhiều cấu hình ví dụ trong kho lưu trữ Tài liệu I/O. Bảo trọng.

Answer 3

I/O Tài liệu hoặc Swagger, là hệ thống tài liệu RESTful API phổ biến nhất. Ngoài ra còn có RAML và Apiary.

Answer 4

test2doc.js giúp bạn tạo tài liệu API từ các bài kiểm tra của bạn/thông số kỹ thuật. Vì vậy, bạn luôn có thể nhận được các tài liệu API cập nhật mới nhất, được điền bằng dữ liệu yêu cầu/phản hồi thực.

Kiểm tra mã ví dụ:

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