使用 ActiveModel 的序列化程序的 Rails API 的 Swagger UI [英] Swagger UI for Rails API using ActiveModel's Serializer

问题描述

我想知道是否有人在使用 Swagger UI 生成 API 文档之前这样做过，而不是由 Swagger 生成的 API.下面是我的一个简单示例:

I was wondering if anyone's done this before where they generate API docs using Swagger UI for an API not also generated by Swagger. Here's what a simple example of mine looks like:

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 文档，并且可以在我看到的地方访问 http://localhost:3000/api-docs.jsonUsers#show 的文档，但是当我单击尝试一下！"时，出现 api/v1/users/show

I've generated the swagger docs with rake swagger:docs and can reach http://localhost:3000/api-docs.json just fine where I see the documentation for Users#show, but when I click "Try it out!", I get a missing template error for 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 而不是视图文件?

How can I render the correct response for my show method so that it looks for the serialized json rather than a view file?

推荐答案

所以，我找到了答案.首先，删除 rake swagger:docs 创建的所有 json 文件，并在 swagger_docs.rb 初始化程序中添加以下内容::clean_directory =>true 这样每次运行 rake swagger:docs 时，都会清除 public 文件夹中的目录.

So, I found the answer. First, delete all the json files created by rake swagger:docs and add into the swagger_docs.rb initializer the following: :clean_directory => true so that everytime rake swagger:docs is run, the directory in public folder is cleared.

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

In order for swagger docs to work with how I'm building my API with ActiveModel's Serializers is to change up the DSL written in Api::V1::UsersController, like so:

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

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

then run rake swagger:docs and the call to show a user should work fine.

这篇关于使用 ActiveModel 的序列化程序的 Rails API 的 Swagger UI的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！