wiki/doc.md · 风吹过的绿洲/smart-swagger - Gitee.com

加入 Gitee

与超过 1200万开发者一起发现、参与优秀开源项目，私有仓库也完全免费：）

该仓库未声明开源许可证文件（LICENSE），使用请关注具体项目描述及其代码上游依赖。

克隆/下载

doc.md 2.57 KB

## 注释规范

### Controller注释
#### 类名注释

| 名称  | 值        | 说明                                              |
| ----- | --------- | ------------------------------------------------- |
| @api  | userModel | api tag值，如果没有，默认取@Path注解的值作为value |
| @desc | 用户模块  | 描述内容， 如果没有，默认取comment                |

#### 参数注释

| 名称              | 值                                                           | 说明                                                         |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| @hidden           | true/false                                                   | 隐藏该方法的api接口                                          |
| @example          | {"success":true,"obj":{"time":"2018-11-10 21:15:32"}}        | 示例请求参数格式                                             |
| @ignoreProperties | password                                                     | 返回body中忽略某个属性，多个使用空格分隔                     |
| @param            | userName 用户名 true                                         | 单个参数添加说明；格式为：参数名+参数含义+是否必须           |
| @return           | custom: {name 名称 string,age 年龄 integer,birthday 生日 string "YYYY-MM-dd HH:mm:ss" "2018-12-10 13:47:26"} | 针对返回map的情况，可以自定义map的属性。格式为custom:{},属性之间用英文逗号分隔。每一个属性值包括参数名、含义、类型、格式、示例。顺序不能改变，其中参数名、含义、类型是必须的。注意：空格冲突时，使用双引号。 |

### Entity实体注释
#### 类名注释
* @entity 实体名称
没有默认取实体comment

#### 属性注释

| 名称      | 值                  | 说明                         |
| --------- | ------------------- | ---------------------------- |
| @desc     | 用户名              | 字段描述，没有默认取comment  |
| @required | true/false          | 是否必须                     |
| @example  | 2018-10-11 15:26:13 | 示例参数值                   |
| @format   | yyyy-MM-dd HH:mm:ss | 参数格式                     |
| @ignore   | true/false          | 是否忽略该字段，例如password |

### 补充

实现JSR303标准的实体验证的框架有hibernate validator 和 oval, 目前还只能支持javax.validation的注解，后续会加入oval的注解。

一键复制编辑原始数据按行查看历史

提交于 2018-12-26 21:31 . fix:修复问题

注释规范

Controller注释

类名注释

名称	值	说明
@api	userModel	api tag值，如果没有，默认取@Path注解的值作为value
@desc	用户模块	描述内容，如果没有，默认取comment

参数注释

名称	值	说明
@hidden	true/false	隐藏该方法的api接口
@example	{"success":true,"obj":{"time":"2018-11-10 21:15:32"}}	示例请求参数格式
@ignoreProperties	password	返回body中忽略某个属性，多个使用空格分隔
@param	userName 用户名 true	单个参数添加说明；格式为：参数名+参数含义+是否必须
@return	custom: {name 名称 string,age 年龄 integer,birthday 生日 string "YYYY-MM-dd HH:mm:ss" "2018-12-10 13:47:26"}	针对返回map的情况，可以自定义map的属性。格式为custom:{},属性之间用英文逗号分隔。每一个属性值包括参数名、含义、类型、格式、示例。顺序不能改变，其中参数名、含义、类型是必须的。注意：空格冲突时，使用双引号。

Entity实体注释

类名注释

@entity 实体名称没有默认取实体comment

属性注释

名称	值	说明
@desc	用户名	字段描述，没有默认取comment
@required	true/false	是否必须
@example	2018-10-11 15:26:13	示例参数值
@format	yyyy-MM-dd HH:mm:ss	参数格式
@ignore	true/false	是否忽略该字段，例如password

补充

实现JSR303标准的实体验证的框架有hibernate validator 和 oval, 目前还只能支持javax.validation的注解，后续会加入oval的注解。

Java

1

https://gitee.com/jay763190097/smart-swagger.git

git@gitee.com:jay763190097/smart-swagger.git

jay763190097

smart-swagger

smart-swagger

master