使用 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.json
Users#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屋!