验证码接口示例

下面以验证码接口为例，说明基本实现方式。

• 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.sa ve
      head 200
    else
      render json: {errors: validation_code.errors}
    end
  end
end

rspec_api_documentation

安装

gem 'rspec_api_documentation'

bundle install

创建文件

mkdir spec/acceptance

code spec/acceptance/validation_codes_spec.rb

编写测试

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

验证并生成文档

请求成功就会生成api文档

bin/rake docs:generate

查看文档：

d doc/api
npx http-server .

完善生成验证码接口

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

• modal 限制email为必填

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

• controller 请求失败返回400
• 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。

• 将使用其它开发者提供的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/

• 修改路径并重新安装

# Gemfile

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

bundle install

• 配置参数
• 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.sa ve
      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