【山竹记账后端】8.【山竹记账后端】测试驱动开发与 API 文档
大纲链接 §
[toc]
|
|
- 输入验证码相关-时序图
1. 测试驱动开发就是先测试再编码 TDD ⇧
安装 rspec_api_documentation
|
|
将
gem 'rspec_api_documentation'复制到GemFile1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23source "https://mirrors.ustc.edu.cn/rubygems/" # source "https://mirrors.tuna.tsinghua.edu.cn/rubygems/" # source "https://rubygems.org" # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main" gem "rails", "~> 7.2.3", ">= 7.2.3.2" # Use postgresql as the database for Active Record gem "pg", "~> 1.1" # Use the Puma web server [https://github.com/puma/puma] gem "puma", ">= 5.0" gem "tzinfo-data", platforms: %i[ mswin mswin64 mingw x64_mingw jruby ] gem "bootsnap", require: false gem "kaminari" gem "rspec_api_documentation" group :development, :test do gem "rspec-rails", "~> 8.0.0" gem "debug", platforms: %i[ mri mswin mswin64 mingw x64_mingw ], require: "debug/prelude" gem "brakeman", require: false gem "rubocop-rails-omakase", require: false end运行
bundle install可忽略以下警告
1 2 3 4Don't run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will break this application for all non-root users on this machine. [DEPRECATED] Your Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source. ...
第一个api用例文档 ⇧
参考文档示例创建两个目录
``zsh mkdir spec/acceptance
vim spec/acceptance/orders_spec.rb
code spec/acceptance/orders_spec.rb ``
spec/acceptance/orders_spec.rb
|
|
运行创建文档命令
|
|
- 运行文档生成命令加前缀
bin/rake docs:generate
发现有报错
|
|
- 是由于未连接数据库造成的
- 在宿主机运行命令
docker start db-for-mangosteen
如果启动失败,比如升级客户端后,删除了之前创建的
Network,可以运行以下命令重新创建数据库
在容器外部宿主机系统运行一行命令
1docker run -d --name db-for-mangosteen -e POSTGRES_USER=mangosteen -e POSTGRES_PASSWORD=123456 -e POSTGRES_DB=mangosteen_dev -e PGDATA=/var/lib/postgresql/data/pgdata -v mangosteen-data:/var/lib/postgresql/data -p 5432:5432 --network=network1 postgres:14注意其中确认
POSTGRES_DB=mangosteen_dev如果已存在,可以先删掉旧的,运行
docker rm -f db-for-mangosteen,再运行创建命令运行命令查看
docker ps成功运行数据库后,再运行文档生成命令
bin/rake docs:generate
再次失败,报错如下:
|
|
- 这是由于生成的初始接口代码目前未实现
spec/acceptance/orders_spec.rb其中的路由不存在
重命名测试文件
spec/acceptance/items_spec.rb
|
|
- 再次运行命令
bin/rake docs:generate
遇到依赖版本
rspec_api_documentation、rack、rack-test不匹配bug问题
引入补丁
spec/support/rspec_api_documentation.rb1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23# spec/support/rspec_api_documentation.rb # 修复 rspec_api_documentation 与 Rack 3 / rack-test 2.2 的兼容问题。 # # 现象:Rack 3 / rack-test 2.2 在 GET 等无请求体的请求中,不会向 env # 中写入 `rack.input`,导致 `last_request.env["rack.input"]` 为 nil。 # rspec_api_documentation 6.1.0 的 ClientBase#read_request_body 会直接对其 # 调用 `rewind`,抛出: # NoMethodError: undefined method `rewind' for nil:NilClass # input.rewind # # 处理:当 rack.input 为 nil 时返回空字符串,避免对 nil 调用 rewind; # 非 nil 时保持原有 rewind + read 行为。 module RspecApiDocumentation class ClientBase def read_request_body input = last_request.env["rack.input"] return "" if input.nil? input.rewind input.read end end end
引入
spec/acceptance/items_spec.rb
|
|
- 再次运行命令
bin/rake docs:generate成功通过测试
使用 http-server 临时查看生成的api文档 ⇧
- 目前自动已生成网页文档:
doc/api/index.html、doc/api/items/listing_items.html 运行
pnpx http-server ./doc/api/即可访问api文档网站http://127.0.0.1:8080/index.html1 2 3# 或者运行以下命令 cd ./doc/api npx http-server .
添加测试用例 validationCode ⇧
创建
touch ./spec/acceptance/validation_codes_spec.rb1 2 3 4 5 6 7 8 9 10 11 12 13require 'rails_helper' require 'rspec_api_documentation/dsl' require_relative '../support/rspec_api_documentation' resource "验证码api" do post "/api/v1/validation_codes" do example "请求发送验证码" do do_request expect(status).to eq 422 end end end首次期待状态码为
422,因为没有传email字段运行
bin/rake docs:generate如果测试通过,就会自动生成文档;如果测试失败,就需要去写代码处理这个问题目前结果如下:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25Generating API Docs Items GET /api/v1/items * Listing items 验证码api POST /api/v1/validation_codes ! 请求发送验证码 (FAILED) Failures: 1) 验证码api POST /api/v1/validation_codes 请求发送验证码 Failure/Error: expect(status).to eq 422 expected: 422 got: 200 (compared using ==) # ./spec/acceptance/validation_codes_spec.rb:10:in `block (3 levels) in <main>' Finished in 0.11129 seconds (files took 0.6342 seconds to load) 2 examples, 1 failure Failed examples: rspec ./spec/acceptance/validation_codes_spec.rb:7 # 验证码api POST /api/v1/validation_codes 请求发送验证码
实现代码 validation_codes_controller.rb ⇧
app/models/validation_code.rb
|
|
app/controllers/api/v1/validation_codes_controller.rb
|
|
- 此时再次运行测试代码
bin/rake docs:generate,测试通过 - 代码只要满足测试用例,就可以生成api文档给前端
- 查看生成文档
pnpx http-server ./doc/api/ - 之后会实现脚本自动部署文档
Body不显示json而是[binary data]之后处理
rails约定大于配置
2. 测试驱动开发就是先测试再编码 ⇧
- 测试驱动开发
Rspec- 生成
Api文档
有个逻辑问题 ⇧
- api文档不应该展示错误,只需要显示正确请求的文档
422 Unprocessable Content是不必要的- 目录名称
acceptance也说明了这一点,只放后端接受前端发的请求 - 如果不接受,最好放到其他目录测试,比如
spec/requests中
测试用例中发送email,添加中文说明 ⇧
spec/acceptance/validation_codes_spec.rb
|
|
- 可以在用例中添加参数的详细描述
- 真实发送成功需要修改返回状态码
- 修改类测试用例代码,需要重新
bin/rake docs:generate - 查看文档
pnpx http-server ./doc/api/http://127.0.0.1:8080Content-Type: application/x-www-form-urlencoded稍后修改为json配置
- 文档
parameter :email, type: :string对参数email的文字描述,生成一个表格let(:email) { '1@qq.com' }对email的赋值do_request自动把参数email带上,自动展示 body 内容
添加
body修改app/controllers/api/v1/validation_codes_controller.rb
|
|
- 重新
bin/rake docs:generate - 查看文档
pnpx http-server ./doc/api/http://127.0.0.1:8080- 后续修改
Body显示错误[binary data]的问题
- 后续修改
参考
3. 解决请求中的JSON问题 ⇧
修改
spec/spec_helper.rb
|
|
:json轻量的字符串
修改
spec/acceptance/validation_codes_spec.rb添加header
|
|
- 重新
bin/rake docs:generate - 查看文档
pnpx http-server ./doc/api/http://127.0.0.1:8080
参考
4. 解决响应中的JSON问题 ⇧
|
|
修改包引用
Gemfile
|
|
- 之后运行命令
bundle或者bundle install - 重新
bin/rake docs:generate - 查看文档
pnpx http-server ./doc/api/http://127.0.0.1:8080 - 需要注意的是不要将含有子仓库的
./vendor/rspec_api_documentation文件提交上去- 进入
cd vendor/rspec_api_documentation删除rm -rf .git - 然后再提交即可
- 进入
参考
回顾 ⇧
- 为了是文档中请求
Header有Content-Type字段,需要在每一次单独请求的时候添加header "Content-Type", "application/json"- 后续可优化
- 为了让请求
Body展示json,需要在spec/rails_helper.rb添加配置config.request_body_formatter = :json - 为了让响应
Body展示json,需要在Gemfile中引用魔改过的版本gem "rspec_api_documentation", path: "./vendor/rspec_api_documentation"
6. 优化每次都要写请求 header ⇧
避免代码重复 修改
spec/spec_helper.rb
|
|
- 重新
bin/rake docs:generate - 查看文档
pnpx http-server ./doc/api/http://127.0.0.1:8080
避免把响应Body中的验证码直接展现给用户 ⇧
spec/acceptance/validation_codes_spec.rb
|
|
app/controllers/api/v1/validation_codes_controller.rb
|
|
参考文章
- 无
相关文章
- 通过 RSpec 生成文档并获得类似 Knife4j 的在线调试与可视化效果
- Let there be docs! Generating an OpenAPI schema across the Rails stack
- Generating OpenAPI docs for Ruby on Rails with RSwag
- Generating OpenAPI docs for Ruby on Rails with RSwag
- github rswag
- github rspec_api_documentation
- 作者: Joel
- 文章链接:
- 版权声明
- 非自由转载-非商用-非衍生-保持署名