Ruby on Rails 如何编写接口文档

TDD 测试驱动开发：借助rspec_api_document测试驱动开发，即完善了接口的功能又能自动生成接口文档。

以验证码接口为例：

• modal

class ValidationCode < ApplicationRecord
end

• router

Rails.application.routes.draw do
      resources :validation_codes, only: [:create]
end

• controller

class ValidationCodesController < ApplicationController
  def create
    code = SecureRandom.random_number.to_s[2..7]
    validation_code = ValidationCode.new email: params[:email], kind: 'sign_in', code: code
    if validation_code.save
      head 200
    else
      render json: {errors: validation_code.errors}
    end
  end
end

rspec_api_documentation

1. 安装

gem 'rspec_api_documentation'

bundle install

2. 创建文件

mkdir spec/acceptance

code spec/acceptance/validation_codes_spec.rb

3. 编写

require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "验证码" do
  post "/validation_codes" do
    example "请求发送验证码" do
      do_request

      expect(status).to eq 200
    end
  end
end

4. 验证

请求成功就会生成api文档

bin/rake docs:generate

查看文档

d doc/api
npx http-server .

完善生成验证码接口

问题1: 测试请求验证码没有传入email参数，返回200

1. modal 限制email为必填

class ValidationCode < ApplicationRecord
    # email必填
    validates :email, presence: true
end

2. controller 请求失败返回400
3. bin/rake docs:generate

问题2: 文档只能显示正确的请求

获取验证码如果未传email(必填参数)将使用示例参数

# spec/acceptance/validation_codes_spec.rb

parameter :email, type: :string
let(:email) { 'apple@x.com' }

请求和响应的body为json格式

由于rspec_api_documentation官方包有bug

1. 将使用其它开发者提供的rspec_api_documentation保存在本地

git clone https://github.com/FrankFang/hTAhuOU4I2QH /vendor/rspec_api_documentation

rm ./vendor/rspec_api_documentation; cp -r /tmp/x/vendor/rspec_api_documentation ./vendor/

2. 修改路径并重新安装

# Gemfile

gem 'rspec_api_documentation', path: './vendor/rspec_api_documentation'

bundle install

3. 配置参数 Configuration options

# spec/spec_helper.rb

require 'rspec_api_documentation'
RspecApiDocumentation.configure do |config|
  config.request_body_formatter = :json
end

config.before(:each) do |spec|
    if spec.metadata[:type].equal? :acceptance
      header 'Accept', 'application/json'
      header 'Content-Type', 'application/json'
    end
  end

code不能作为响应字段显示在文档上

# controllers/api/v1/validation_codes_controller.rb

class Api::V1::ValidationCodesController < ApplicationController
  def create
    code = SecureRandom.random_number.to_s[2..7]
    validation_code = ValidationCode.new email: params[:email], kind: 'sign_in', code: code
    if validation_code.save
      render status: 200
    else
      render json: {errors: validation_code.errors}, status: 400
    end
  end
end

# spec/acceptance/validation_codes_spec.rb

require 'rails_helper'
require 'rspec_api_documentation/dsl'

resource "验证码" do
  post "/api/v1/validation_codes" do
    
    parameter :email, type: :stri
    let(:email) { 'apple@x.com' }
    example "请求发送验证码" do
      do_request
      expect(status).to eq 200
      expect(response_body).to eq ' '
    end
  end
end

参考：github.com/zipmark/rsp…