# swagger-grails4

**Repository Path**: dbb_admin/swagger-grails4

## Basic Information

- **Project Name**: swagger-grails4
- **Description**: No description available
- **Primary Language**: Groovy
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-12
- **Last Updated**: 2024-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= swagger-grails4
:icons: font
:stem:
:toc:
:toclevels: 6
:sectnums:
:sectnumlevels: 6

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

== 用法

=== 软件版本

1. Grails v4 or greater
2. Java 1.8
3. Groovy 2.5

=== 基本使用步骤

==== 指定 gradle 依赖

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

==== 添加 @ApiDoc 注解

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

.添加 @ApiDoc 到Controller:
[source,groovy]
----
@ApiDoc(tag = {
    description "User API"
})
class UserController {
}
----

.添加 @ApiDoc 到 action 方法:
[source,groovy]
----
@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 类
[source,groovy]
----
@ApiDoc("The command contains User properties")
class UserCommand implements Validateable{
    /**
     * The name of user in comments.
     */
    String username
}
----

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

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

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

==== 更多控制

.你可以用@ApiDoc替换字段的注释内容
[source,groovy]
----
@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 来描述参数
[source,groovy]
----
@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**就对应一个
https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#parameterObject[Parameter] object,
所以你可以使用任何 Parameter 类的'基础类型属性'例如 name、description 等，而复杂对象需要特殊处理，有可能还未支持。
另外 Parameter 的**in**属性对应的是**inType**，因为in是groovy的关键字。

===== 更多的Response文档化技术

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

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

.假设 response 类像这样：
[source,groovy]
----
@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 对象
[source,groovy]
----
@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
[source,groovy]
----
@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"
[source,groovy]
----
@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
[source,groovy]
----
@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() {
}
----

== 特色功能

- 从 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 文档快乐!

== 关于作者

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