自动生成 Swagger/OpenAPI-v3 文档的 Grails 插件
repositories {
maven { url "https://dl.bintray.com/bobyang/plugins" }
// or jcenter()
}
dependencies {
implementation 'swagger.grails4:swagger-grails4:0.0.1'
}
添加 @ApiDoc 注解到 Controller 和 Command、Domain 类或者任何需要文档的类上。 插件会自动抽取“字段”的注释作为OpenAPI的描述内容。
@ApiDoc(tag = {
description "User API"
})
class UserController {
}
@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("The command contains User properties")
class UserCommand implements Validateable{
/**
* The name of user in comments.
*/
String username
}
现在启动你的 REST api grails 应用程序,访问 "http://<host:port>/api/doc", 就能看到 swagger-ui 的文档了。
访问 "http://<host:port>/api/doc", 就能取到文档对应的 json 对象。
@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 等,那么你可以这样对它们进行文档化。
@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的关键字。
你可以修改 Response schema 的 properties 内容。
假如你的 api response 对象在不同的action中会返回不同的信息类,那么使用下面的技术就会很方便了。
@ApiDoc("A test rest api response class")
class RestApiResponse {
/**
* Error code
*/
int code
/**
* Message
*/
String msg
/**
* Return payload
*/
Object info
}
@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。
@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 类型。
@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() {
}
@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 系统的公司。 我们在中国北京,如果您对我们的服务和产品感兴趣,请联系我们,我们的联系邮箱是 [email protected]。