我正在运行 Grails 3.0.11 并希望为我的 REST 端点创建 Swagger 文档.我添加了 SwaggyDoc-plugin 添加到我的 build.gradle 脚本中的依赖项:
I am running Grails 3.0.11 and want to create Swagger-documentation for my REST endpoints. I added the SwaggyDoc-plugin to the dependencies in my build.gradle script by adding:
compile "org.grails.plugins:swaggydoc:0.26.0".
在 IntelliJ 中，我看到 Swaggydoc 依赖项已添加到我的库列表中.
In IntelliJ I see the Swaggydoc-dependency added to my list of libraries.
通过 grails run-app 命令启动我的 Grails 应用程序并通过输入 http://localhost 打开我的应用程序后:8080/api/ 我得到一个 404 错误，告诉页面不存在.
After starting my Grails-application via the grails run-app command and opening my application by entering http://localhost:8080/api/ I get an 404 error telling the page does not exist.
我是否需要配置更多或运行一些特殊的东西来生成文档?我已经尝试在 Git 项目中开票并联系作者，但没有成功.
Do I need to configure something more or to run something special to generate documentation? I already tried to open a ticket in the Git-project and contacting the author with no succes.
Update1:我添加了一个 Grails 3 插件(在 Versioneye 中找到?):
Update1: there seems to be a Grails 3-plugin (found at Versioneye?) which I added:
compile "org.grails.plugins:swaggydoc-grails3:0.26.0"
它确实工作了一半，默认情况下某种宠物演示是可见的，并且它在域和枚举中的约束上失败.实际上似乎不太好用.
It does work half, by default some sort of Pet-demo is visible and it is failing on constraints in a domain and enums. Doesn't seem to work very well actually.
Update2:正如 Dilip Krishnan 所指出的，我尝试使用 SpringFox，首先我将依赖项添加到我的 Gradle 构建文件中:
Update2: As pointed out by Dilip Krishnan I tried to use SpringFox, first I added the dependencies to my Gradle build file:
compile("io.springfox:springfox-swagger2:2.3.1")
compile("io.springfox:springfox-swagger-ui:2.3.1")
然后我添加了一个名为 ApiDocumentationConfiguration 的新类，代码如下:
Then I added a new class called ApiDocumentationConfiguration with the following code:
@Configuration
@EnableSwagger2
public class ApiDocumentationConfiguration {
@Bean
public Docket documentation() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
@Bean
public UiConfiguration uiConfig() {
return UiConfiguration.DEFAULT;
}
private ApiInfo metadata() {
return new ApiInfoBuilder()
.title("My awesome API")
.description("Some description")
.version("1.0")
.contact("my-email@domain.org")
.build();
}
}
我的 Grails 资源文件包含以下代码:
My Grails resources file contains the following code:
beans = {
apiDocumentationConfiguration(ApiDocumentationConfiguration)
}
最后一步是启动应用程序并尝试加载显示 Swagger 前端的端点:
Last step was starting the application and trying to load the end point which shows the Swagger front end:
http://localhost:8080/swagger-ui.html
它在幕后尝试加载另一个端点(我猜是包含 JSON?)，它加载了
It behind the scenes tries to load an other end point (containing the JSON I guess?) which loads
http://localhost:8080/v2/api-docs
这确实显示了 JSON 数据，我得到了基本错误控制器、健康 mvc、指标 mvc 等的端点.但不是我自己的注释用户控制器，其注释如下:
This does show JSON data and I get end points for things like a basic error controller, health mvc, metrics mvc et cetera. But not my own annotated user controller which is annotated like follows:
@Api(value = "users", description = "Endpoint for user management")
class UserController {
// GET all users
@ApiOperation(value = "doStuff", nickname = "doStuff", response = User.class)
def index() {
respond User.list()
}
}
似乎我快到了，但仍然缺少一些东西，是我的注释错误还是没有扫描我的控制器?
Seems I am almost there, but still missing something, is my annotation wrong or doesn't it scan my controllers?
Update3:与 SpringFox 的一位作者 (Dilip Krishnan) 联系以向 SpringFox 添加对 Grails 3+ 的支持，请参阅 票.它目前不起作用的原因是因为 SpringFox 查看 MVC 注释，需要编写一个适配器来从 Grails 中的控制器检索端点.
Update3: in contact with one of the authors of SpringFox (Dilip Krishnan) to add support for Grails 3+ to SpringFox, see ticket. The reason it doesn't currently work is because SpringFox looks at MVC annotation, an adapter needs to be written to retrieve the endpoints from the controllers in Grails.
推荐答案
我已经在 2.4.x 和 3.1.4 项目中成功使用了 swaggydocs.为了使其在 3.x 中工作(在 3.1.4 上测试)，您必须添加
I have successfully used swaggydocs in both 2.4.x projects and 3.1.4. In order to make it work in 3.x (tested on 3.1.4) you have to add
compile "org.grails.plugins:swaggydoc-grails3:0.26.0"
到 gradle 依赖部分.这使您的项目中可以使用 swaggy.
to gradle dependencies section. That makes swaggy available in your project.
然后给你的控制器添加注解
Then add annotations to your controllers
@Api("test methods")
class TestController {
@ApiOperation(value = "some method description")
@ApiResponses([
@ApiResponse(code = 405, message = "Bad method. Only POST is allowed"),
@ApiResponse(code = 401, message = "Unauthorized"),
@ApiResponse(code = 400, message = "Invalid request json")
])
def testGetMethod() {
render([status: "OK"] as JSON)
}
然后将你的方法标记为 allowedMethods 如下
Then mark your methods allowedMethods as follows
class TestController {
static allowedMethods = [testGetMethod: "GET", testPostMethod: "POST"]
注意这非常重要 - 否则 swaggy 会将您的每个方法标记为 GET.Swaggy 既不尊重 ApiOperation 注释中的 httpMethod，也不尊重 url 映射中的 http 方法.
NOTE this is really important - otherwise swaggy will mark every your method as GET. Swaggy doesn't respect neither httpMethod in ApiOperation annotation nor http method in url mappings.
最后将您的控制器添加到 urlmappings，因为 swaggy 检查 url 映射以查找 URL.注意驼峰式！
Finally add your controller to urlmappings as swaggy checks url mappings to look for URLS. Note camelCase!
//NOTE small camelCase
//swaggy won't see urls correctly if you start controller name with capital letter
"/api/test/"(controller: "test", action: "testGetMethod")
"/api/test/"(controller: "test", action: "testPostMethod")
你也可以在application.yml中添加一些api信息
You can also add some api info in application.yml
swaggydoc:
contact: rafal@pydyniak.pl
description: sample swaggy app
您可以在我的 github https://github.com/RafalPydyniak/Swaggy-example.还有一些关于如何在 http://rahulsom.github.io/swaggydoc/上使用这个 api 的文档/a>.我只是想向您展示如何安装它(因为要让一切正常工作非常棘手)
You can find sample app (with dummy methods but point was to make swaggy work) at my github https://github.com/RafalPydyniak/Swaggy-example. Also there are some more docs on how to use this api on http://rahulsom.github.io/swaggydoc/. I just wanted to show you how to install it (as it's quite tricky to make everything work)
希望对你有帮助！
相关推荐
最新文章