Skip to content

Latest commit

 

History

History
271 lines (229 loc) · 7.15 KB

README_zh.adoc

File metadata and controls

271 lines (229 loc) · 7.15 KB
Raw

swagger-grails4

Table of Contents

自动生成 Swagger/OpenAPI-v3 文档的 Grails 插件

1. 用法

1.1. 软件版本

  1. Grails v4 or greater

  2. Java 1.8

  3. Groovy 2.5

1.2. 基本使用步骤

1.2.1. 指定 gradle 依赖

repositories {
  maven { url "https://dl.bintray.com/bobyang/plugins" }
  // or jcenter()
}
dependencies {
  implementation 'swagger.grails4:swagger-grails4:0.0.1'
}

1.2.2. 添加 @ApiDoc 注解

添加 @ApiDoc 注解到 Controller 和 Command、Domain 类或者任何需要文档的类上。 插件会自动抽取“字段”的注释作为OpenAPI的描述内容。

添加 @ApiDoc 到Controller:
@ApiDoc(tag = {
    description "User API"
})
class UserController {
}
添加 @ApiDoc 到 action 方法:
@ApiDoc(operation = {
    summary "Create User"
    description "Create a new user"
    responses "200": {
        content "default": {
            description "success response"
            schema MyApiResponse
        }
    }
})
def createUser(UserCommand command) {
}

插件会自动抽取 command class 字段的注释作为文档的描述信息。 如果你在字段上添加了 @ApiDoc 注解，那么会优先使用注解的内容。

添加 @ApiDoc 注解到 command 类或者 domain 类
@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
    /**
     * The name of user in comments.
     */
    String username
}

1.2.3. API文档的 JSON 端点和HTML文档的URL地址

现在启动你的 REST api grails 应用程序，访问 "http://<host:port>/api/doc"， 就能看到 swagger-ui 的文档了。

访问 "http://<host:port>/api/doc", 就能取到文档对应的 json 对象。

1.2.4. 更多控制

你可以用@ApiDoc替换字段的注释内容
@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
    /**
     * The name of user in comments.
     */
    @ApiDoc("The name of user")
    String username
}

如果 action 方法的参数是基础类型，例如 Integer、String 等，那么你可以这样对它们进行文档化。

使用 OpenAPI Parameter model 来描述参数
@ApiDoc(operation = {
    summary "Login"
    description "Login with user name and password"
    parameters([{
                    name "username"
                    description "User Name"
                    inType "query"
                    schema { type "string" }
                }, {
                    name "password"
                    description "Password"
                    inType "query"
                    schema { type "string" }
                }])
})
def login(String password, String username) {
}

在’annotation closure'(Groovy的一个技术) 中每一个parameter就对应一个 Parameter object, 所以你可以使用任何 Parameter 类的’基础类型属性’例如 name、description 等，而复杂对象需要特殊处理，有可能还未支持。 另外 Parameter 的in属性对应的是inType，因为in是groovy的关键字。

1.2.4.1. 更多的Response文档化技术

你可以修改 Response schema 的 properties 内容。

假如你的 api response 对象在不同的action中会返回不同的信息类，那么使用下面的技术就会很方便了。

假设 response 类像这样：
@ApiDoc("A test rest api response class")
class RestApiResponse {
    /**
     * Error code
     */
    int code
    /**
     * Message
     */
    String msg
    /**
     * Return payload
     */
    Object info
}
重载 response 类的 properties，因为在本 action 中 info 属性返回的是 UserCommand 对象
@ApiDoc(operation = {
    summary "Login"
    description "Login with user name and password"
    responses "200": {
        content "default": {
            description "success response"
            schema RestApiResponse, properties: [info: UserCommand]
        }
    }
})
def login(LoginCommand loginCommand) {
}

你甚至可以在 annotation closure 中完全重新定义 schema。

在 annotation closure 中定义 schema
@ApiDoc(operation = {
    summary "Create User"
    description "Create a new user"
    responses "200": {
        content "default": {
            description "success response"
            schema {
                name "CustomSchema"
                type "string"
                description "The customized json response"
            }
        }
    }
})
def createUser(UserCommand command) {
}

你可以在 responses 项中说明多个 "Status Code" 以及 content MIME 类型。

说明多个"Status Code"
@ApiDoc(operation = {
    summary "List Users"
    description "List users, support query and paging parameters"
    responses "200": {
        content "default": {
            description "success response"
            schema RestApiResponse
        }
    }, "201": {
        content "default": {
            description "success response with 201"
            schema UserCommand
        }
    }
})
def index() {
}
说明多个"MIME" content
@ApiDoc(operation = {
    summary "List Users"
    description "List users, support query and paging parameters"
    responses "200": {
        content "default": {
            description "success response"
            schema RestApiResponse
        }, "text/xml": {
            description "success response with 201"
            schema UserCommand
        }
    }
})
def index() {
}

2. 特色功能

  • 从 grails controller 和 UrlMapping 中自动创建 operations 模型

  • 从任何添加了 @ApiDoc 注解的类中自动抽取 Schema 模型

  • 自动抽取类的 fields 的注释来创建 properties 的描述内容

  • 自动创建包含所有 Enum 枚举类型值的说明文档，如果枚举对象有 id 属性，那么会显示对应的id值

  • 自动创建数组的成员类型的文档，即 array 的成员的Schema

  • 正确处理“循环引用”

    所谓的“循环引用”是指类A中有一个属性的类型是类B，而类B中有一个属性的类型是类A，或者类B的属性间接引用到类A。
    因为swagger-ui在遇到“循环引用”情况时，会导致界面挂起，所以我们会在遇到循环引用时终止引用。

  • 在开发环境中隐藏 API DOC 功能

  • 自动生成 response 对象文档

  • response Schema 的’properties’可以被定制、改写

  • TODO: Can handle inherited trait properties and plain class properties.

  • TODO: recognize GORM association properties.

如果你需要更多的功能，请提交一个带有’enhancement’标签的issue，欢迎多提意见、建议。

希望这个插件能节省你编写繁冗的API文档的时间。

祝使用 'swagger-grails4' 插件编写 Grails REST API 文档快乐!

3. 关于作者

我们是北京塔尔旺科技有限公司，一家提供软件开发服务和电商 SaaS 系统的公司。 我们在中国北京，如果您对我们的服务和产品感兴趣，请联系我们，我们的联系邮箱是 [email protected]。