Grails 3+ (3.0.11) 中的 Swagger 2.0 支持不起作用

Question

我正在运行 Grails 3.0.11 并希望为我的 REST 端点创建 Swagger 文档。我将 SwaggyDoc-plugin 添加到我的 build.gradle 脚本中的依赖项中，方法是添加：

compile "org.grails.plugins:swaggydoc:0.26.0".

在 IntelliJ 中，我看到 Swaggydoc 依赖项已添加到我的库列表中。

通过 grails run-app 命令启动我的 Grails 应用程序并输入 http://localhost:8080/api/ 打开我的应用程序后，我收到一个 404 错误，提示该页面不存在。

我是否需要配置更多或运行一些特殊的东西来生成文档？我已经尝试在 Git 项目中开票并联系作者，但没有成功。

Update1：我添加了一个 Grails 3 插件（在 Versioneye 中找到？）：

compile "org.grails.plugins:swaggydoc-grails3:0.26.0"

它确实工作了一半，默认情况下某种宠物演示是可见的，并且它在域和枚举中的约束上失败。实际上似乎不太好用。

Update2：正如 Dilip Krishnan 所指出的，我尝试使用 SpringFox，首先我将依赖项添加到我的 Gradle 构建文件中：

compile("io.springfox:springfox-swagger2:2.3.1")
compile("io.springfox:springfox-swagger-ui:2.3.1")

然后我添加了一个名为 ApiDocumentationConfiguration 的新类，代码如下：

 @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 资源文件包含以下代码：

beans = {
    apiDocumentationConfiguration(ApiDocumentationConfiguration)
}

最后一步是启动应用程序并尝试加载显示 Swagger 前端的端点：

http://localhost:8080/swagger-ui.html

它在幕后尝试加载另一个端点（我猜是包含 JSON？），它加载了

http://localhost:8080/v2/api-docs

这确实显示了 JSON 数据，我得到了基本错误控制器、健康 mvc、指标 mvc 等的端点。但不是我自己的注释用户控制器，其注释如下：

@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()
    }
}

似乎我快到了，但仍然缺少一些东西，是我的注释错误还是没有扫描我的控制器？

Update3：与 SpringFox 的一位作者 (Dilip Krishnan) 联系以向 SpringFox 添加对 Grails 3+ 的支持，请参阅 ticket。它目前不起作用的原因是因为 SpringFox 查看 MVC 注释，需要编写一个适配器来从 Grails 中的控制器检索端点。

Answer 1

我在 2.4.x 项目和 3.1.4 中都成功使用了 swaggydocs。 为了使其在 3.x 中工作（在 3.1.4 上测试），您必须添加

    compile "org.grails.plugins:swaggydoc-grails3:0.26.0"

到 gradle 依赖部分。这使您的项目中可以使用 swaggy。

然后给你的控制器添加注解

@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 如下

class TestController {
static allowedMethods = [testGetMethod: "GET", testPostMethod: "POST"]

注意这非常重要 - 否则 swaggy 会将您的每个方法标记为 GET。 Swaggy 既不尊重 ApiOperation 注释中的 httpMethod，也不尊重 url 映射中的 http 方法。

最后将您的控制器添加到 urlmappings，因为 swaggy 检查 url 映射以查找 URL。注意驼峰式！

//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信息

swaggydoc:
    contact: rafal@pydyniak.pl
    description: sample swaggy app

您可以在我的 github https://github.com/RafalPydyniak/Swaggy-example 上找到示例应用程序（使用虚拟方法，但重点是让工作变得更时髦）。 还有更多关于如何在http://rahulsom.github.io/swaggydoc/ 上使用此 api 的文档。我只是想向您展示如何安装它（因为要让一切正常工作非常棘手）

希望对你有帮助！

Answer 2

我遵循了相同的两个步骤： 1）添加swagger2依赖 2) 提供配置 问题是 sprinfox 不扫描 grails url 映射（参见https://github.com/springfox/springfox/issues/1169#issuecomment-252259284） 为了解决这个问题，我添加了标准弹簧注释：

@Controller()
@RequestMapping(value="/path")

在控制器上和

@RequestMapping(value="/resource")

关于方法。之后，sprinfox 开始接收我的文档。