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"

它确实工作了一半，默认情况下某种Pet-demo是可见的，它在域和枚举中的约束失败。实际上看起来效果不好。

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

My 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)
}

然后将您的方法标记为allowMethods，如下所示

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

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

最后将您的控制器添加到urlmappings作为swaggy检查url映射以查找URL。注意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信息

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 mappings（参见https://github.com/springfox/springfox/issues/1169#issuecomment-252259284）为了解决这个问题，我添加了标准的spring注释：

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

控制器上的

和

@RequestMapping(value="/resource")

关于方法。之后sprinfox开始拿起我的文档。

Grails 3+（3.0.11）中的Swagger 2.0支持不起作用

2 个答案: