Grails 3+(3.0.11)中的Swagger 2.0支持不起作用 [英] Swagger 2.0 support in Grails 3+ (3.0.11) not working

问题描述

我正在运行Grails 3.0.11，并想为我的REST端点创建Swagger文档.我添加了 SwaggyDoc -插件添加到我的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-plugin(在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"

它确实可以正常工作一半，默认情况下，某种Pet-demo可见，并且在域和枚举中的约束失败.实际上似乎不太好用.

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("[e-mail]")
            .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)联系，以将对Grails 3+的支持添加到SpringFox，请参见

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依赖项部分.这使您的项目中可以使用杂项.

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

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

Then mark your methods allowedMethods as follows

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

请注意，这确实很重要-否则，拖延状态会将您的每个方法都标记为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.注意camelCase！

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: [e-mail]
    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)

希望有帮助！

这篇关于Grails 3+(3.0.11)中的Swagger 2.0支持不起作用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！