rswag 使用指南

rswag 使用指南

rswagSeamlessly adds a Swagger to Rails-based API's项目地址:https://gitcode.com/gh_mirrors/rs/rswag

1. 项目目录结构及介绍

rswag 是一个专为 Ruby on Rails 应用设计的工具，用于无缝集成 Swagger（现称为 OpenAPI）到你的 API 文档中。以下是一般化的 rswag 项目可能会有的典型目录结构及其简要说明：

.
├── app                     # 包含应用的业务逻辑，如控制器、模型等
│   └── ...
├── config                  # 配置相关，包括 routes.rb，以及 rswag 特定的初始化文件
│   ├── initializers
│   │   ├── rswag_api.rb     # rswag-api 的配置文件
│   │   └── rswag-ui.rb      # rswag-ui 的配置文件
│   └── ...
├── spec                    # 测试目录，包含 rspec 集成测试
│   └── requests            # 或 spec/api, spec/integration，存放 rswag 编写的测试
│       └── api_spec.rb     # 示例的 rswag 测试文件
├── Gemfile                 # 项目依赖管理文件
└── ...

在 spec 目录下，rswag 的特色在于通过特定的测试描述 API 操作，这些测试最终被用于自动生成 Swagger 文件。

2. 项目启动文件介绍

在 Rails 环境中，并没有单一的“项目启动文件”，但有关键的配置文件和路由设置，对于 rswag 而言，关注点主要在两个配置文件：

• config/routes.rb : 这里定义了应用的所有路由，对于 rswag 来说，它将添加Swagger文件的访问路由。

• config/initializers/rswag.rb* : 这些文件中进行rswag的具体配置，比如rswag_api.rb和rswag-ui.rb分别配置 API JSON端点的暴露方式和swagger-ui的集成设置。

为了使rswag工作，你需要在 routes.rb 中引入并配置相关的引擎：

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => '/swagger-ui'
  mount Rswag::Api::Engine => '/api-docs'
  # 其他路由...
end

3. 项目的配置文件介绍

rswag-api 配置

位于 config/initializers/rswag_api.rb 的配置文件允许你定制 Swagger JSON 文件的根路径。例如：

Rswag::Api.configure do |config|
  config.openapi_root = Rails.root.to_s + '/your-custom-folder-name'
end

这决定了 Swagger JSON 文件的存储位置，并且如何通过API访问它们。

rswag-specs 使用

尽管不是单独的启动或配置文件，但 spec/swagger_helper.rb 自动由 rswag-specs 生成，用于控制生成的Swagger文件的位置，示例配置：

RSpec.configure do |config|
  config.openapi_root = Rails.root.to_s + '/your-custom-folder-name'
end

确保与 rswag-api 的配置相匹配，以便正确地映射文件路径。

总结来说，rswag 的使用涉及到对 Rails 工程特定目录下的配置和初始化文件的调整，以实现文档的自动化生成与集成测试的紧密结合。通过精心配置这些环节，能够极大地简化 API 文档的维护与测试流程。

rswagSeamlessly adds a Swagger to Rails-based API's项目地址:https://gitcode.com/gh_mirrors/rs/rswag