Swagger UI for Rails API 使用 ActiveModel 的 Serializer

Question

我想知道是否有人在使用 Swagger UI 生成 API 文档之前完成过此操作，而 API 也不是由 Swagger 生成的。这是我的一个简单示例：

class Api::V1::UsersController < Api::V1::BaseController
  swagger_controller :users, 'Users'

  swagger_api :show do
    summary 'Returns a user'
    param :path, :id, :integer, :optional, "User Id"
    notes '/api/v1/users/:id'
    response :ok, "Success", :Users
    response :unauthorized
    response :not_acceptable
    response :not_found
  end

  def show
    user = User.find(params[:id])

    render(json: Api::V1::UserSerializer.new(user).to_json)
  end
end

我已经使用 rake swagger:docs 生成了 swagger 文档，并且可以在我看到 Users#show 的文档的地方到达 http://localhost:3000/api-docs.json，但是当我单击 "Try it out!" 时，我收到 api/v1/users/show

的模板丢失错误

api-docs.json:

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000",
  "apis": [
    {
      "path": "/api/v1/users.{format}",
      "description": "Users"
    }
  ],
  "authorizations": null
}

users.json:

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:3000",
  "resourcePath": "users",
  "apis": [
    {
      "path": "/api/v1/users/{id}.json",
      "operations": [
        {
          "summary": "Returns a user",
          "parameters": [
            {
              "paramType": "path",
              "name": "id",
              "type": "integer",
              "description": "User Id",
              "required": false
            }
          ],
          "notes": "/api/v1/users/:id",
          "responseMessages": [
            {
              "code": 200,
              "responseModel": "Users",
              "message": "Success"
            },
            {
              "code": 401,
              "responseModel": null,
              "message": "Unauthorized"
            },
            {
              "code": 404,
              "responseModel": null,
              "message": "Not Found"
            },
            {
              "code": 406,
              "responseModel": null,
              "message": "Not Acceptable"
            }
          ],
          "nickname": "Api::V1::Users#show",
          "method": "get"
        }
      ]
    }
  ],
  "authorizations": null
}

如何为我的 show 方法呈现正确的响应，以便它查找序列化的 json 而不是视图文件？

Answer 1

所以，我找到了答案。首先，删除由 rake swagger:docs 创建的所有 json 文件，并在 swagger_docs.rb 初始值设定项中添加以下内容： :clean_directory => true 以便每次 rake swagger:docs 都是运行 , public 文件夹中的目录被清除。

为了让 swagger 文档与我使用 ActiveModel 的序列化程序构建 API 的方式一起工作，需要更改用 Api::V1::UsersController 编写的 DSL，如下所示：

  swagger_api :show do
    summary 'Returns a user'
    param :path, :id, :integer, :optional, "User Id"
    notes '/api/v1/users/:id'
  end

然后运行 rake swagger:docs 并且显示用户的调用应该可以正常工作。

Swagger UI for Rails API 使用 ActiveModel 的 Serializer

Swagger UI for Rails API using ActiveModel's Serializer

ruby-on-rails

swagger

active-model-serializers

swagger-ui