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

Question

我正在运行Grails 3.0.11并希望为我的REST端点创建Swagger文档.我通过添加以下内容将SwaggyDoc - 插件添加到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)
}

然后将您的方法allowedMethods标记如下

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的文档.我只想告诉你如何安装它(因为让一切工作都很棘手)

希望能帮助到你!