如何实现readme.io中Rails API文档的自动更新？

核心工具：rswag（Rails Swagger生成器） #

rswag是Rails生态中最常用的API文档生成工具，能直接从控制器注释生成符合OpenAPI规范的Swagger文档，再通过readme.io的API同步到平台。

操作流程 #

1. 安装并初始化rswag
   在Gemfile中添加依赖：

   gem 'rswag-api'
   gem 'rswag-ui'
   

   执行bundle install，然后运行初始化命令：

   rails generate rswag:install
   rails generate rswag:specs:install
   

2. 在控制器中添加规范注释
   给API控制器的每个动作添加符合Swagger规范的注释，示例：

   class Api::V1::UsersController < ApplicationController
     # GET /api/v1/users
     # @param page [Integer] 分页页码，默认1
     # @return [Array<User>] 用户列表，包含id、name、email字段
     def index
       @users = User.paginate(page: params[:page] || 1, per_page: 10)
       render json: @users
     end
   end
   

3. 生成Swagger JSON文件
   运行命令生成标准的Swagger文档：

   rails rswag:specs:swaggerize
   

   生成的文件会存放在swagger/v1/swagger.json路径下。

4. 编写同步脚本并执行
   利用readme.io的API上传Swagger文件，可写一个Rake任务自动化：

   # lib/tasks/sync_readme_api.rake
   namespace :readme do
     desc "同步Rails API文档到readme.io"
     task sync_api_docs: :environment do
       require 'net/http'
       require 'json'
   
       swagger_path = Rails.root.join('swagger', 'v1', 'swagger.json')
       swagger_content = JSON.parse(File.read(swagger_path))
       api_key = ENV['README_IO_API_KEY']
       project_slug = ENV['README_IO_PROJECT_SLUG']
   
       uri = URI("https://dash.readme.io/api/v1/api-specs/#{project_slug}")
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
   
       request = Net::HTTP::Put.new(uri)
       request['Authorization'] = "Bearer #{api_key}"
       request['Content-Type'] = 'application/json'
       request.body = swagger_content.to_json
   
       response = http.request(request)
       puts response.code == '200' ? "文档同步成功！" : "同步失败：#{response.body}"
     end
   end
   

   设置环境变量README_IO_API_KEY（从readme.io账户的API设置中获取）和README_IO_PROJECT_SLUG（你的项目专属标识），然后执行：

   rake readme:sync_api_docs
   

5. CI/CD自动化同步
   将上述Rake任务加入你的CI/CD流程（比如GitHub Actions、GitLab CI），每次代码合并到主分支时自动运行，实现文档的自动更新。

备选工具：OpenAPI Generator #

如果已有现成的OpenAPI/Swagger文档，可使用OpenAPI Generator转换格式后，再通过readme.io API上传。不过rswag更贴合Rails项目的开发流程，无需额外维护独立的文档文件。

内容的提问来源于stack exchange，提问作者abubakar nawaz