spring - 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 项目中打开一张票并联系作者但没有成功。

更新 1 :似乎有一个 Grails 3 插件(在 Versioneye 上找到？)，我添加了:

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

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

更新 2 :正如 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 数据，我得到了基本错误 Controller 、健康 mvc、指标 mvc 等的端点。但不是我自己的带注释的用户 Controller ，其注释如下:

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

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

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

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 在您的项目中可用。

然后向您的 Controller 添加注释

@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 方法。

最后将您的 Controller 添加到 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 的文档。 .我只是想向您展示如何安装它(因为让一切正常工作非常棘手)

希望能帮助到你!