Zero-Rails OpenAPI 使用教程

Zero-Rails OpenAPI 使用教程

zero-rails_openapiConcise DSL for generating OpenAPI Specification 3 (OAS3) JSON documentation for Ruby application.项目地址:https://gitcode.com/gh_mirrors/ze/zero-rails_openapi

1. 项目介绍

Zero-Rails OpenAPI 是一个用于为 Rails 应用生成 OpenAPI Specification 3 (OAS3) 标准 JSON 文档的 Ruby Gem。它提供了一套简洁的 DSL（领域特定语言），帮助开发者快速生成 API 文档，并支持 Swagger-UI 进行可视化展示。

2. 项目快速启动

安装

首先，在 Gemfile 中添加以下内容：

gem 'zero-rails_openapi'

然后执行：

bundle install

配置

在 config/initializers 目录下创建一个初始化文件 open_api.rb，并添加以下配置：

require 'open_api'

OpenApi::Config.class_eval do
  # 配置文件输出路径
  self.file_output_path = 'public/open_api'

  # OpenAPI 文档信息
  open_api :doc_name, base_doc_classes: [ApiDoc] do
    info version: '1.0.0', title: 'Homepage APIs'
    server 'http://localhost:3000', desc: 'Internal staging server for testing'
    bearer_auth :Authorization
  end
end

生成文档

在 Rails 控制器中使用 DSL 定义 API：

class Api::V1::ExamplesController < ApplicationController
  include OpenApi::DSL

  api :index, '获取示例列表' do
    desc '获取所有示例的列表'
    response_schema 'ExampleList', :ok
  end

  def index
    examples = Example.all
    render json: examples
  end
end

运行以下命令生成文档：

rails open_api:write_docs

生成的文档将保存在 public/open_api 目录下。

3. 应用案例和最佳实践

应用案例

假设你正在开发一个博客应用，使用 Zero-Rails OpenAPI 可以轻松生成 API 文档。例如，定义一个获取文章列表的 API：

class Api::V1::ArticlesController < ApplicationController
  include OpenApi::DSL

  api :index, '获取文章列表' do
    desc '获取所有文章的列表'
    response_schema 'ArticleList', :ok
  end

  def index
    articles = Article.all
    render json: articles
  end
end

最佳实践

1. 分离文档定义与控制器：将 API 文档定义与控制器逻辑分离，保持代码整洁。
2. 复用组件：在 components 块内定义可复用的组件，如参数、响应格式等。
3. 自动化测试：结合 RSpec 等测试工具，确保生成的文档与实际 API 行为一致。

4. 典型生态项目

Swagger-UI

Swagger-UI 是一个用于可视化 OpenAPI 文档的工具。你可以将生成的 JSON 文档导入 Swagger-UI，以便更直观地查看和测试 API。

RSpec

结合 RSpec 进行自动化测试，确保 API 文档的准确性。例如：

RSpec.describe Api::V1::ArticlesController, type: :controller do
  describe 'GET #index' do
    it 'returns a list of articles' do
      get :index
      expect(response).to have_http_status(:ok)
      expect(JSON.parse(response.body)).to be_an(Array)
    end
  end
end

通过这些工具和实践，你可以更高效地开发和维护 Rails 应用的 API 文档。

zero-rails_openapiConcise DSL for generating OpenAPI Specification 3 (OAS3) JSON documentation for Ruby application.项目地址:https://gitcode.com/gh_mirrors/ze/zero-rails_openapi