简介
官网
github
swagger-springmvc: https://github.com/martypitt/swagger-springmvc
swagger-ui: https://github.com/swagger-api/swagger-ui
swagger-core: https://github.com/swagger-api/swagger-core
swagger-spec：https://github.com/swagger-api/swagger-spec
swagger的作用
1.接口的文档在线自动生成。
2.功能测试。
为什么要用swagger？
为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
- 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
- 随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
常用注解
| 注解 | 作用 | 示例 |
| @Api | 用在Controller类上 | @Api(value = "用户管理类", description = "Operations about user") |
| @ApiOperation | 用在Controller方法上 | @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) |
| @ApiImplicitParam | 用在Controller方法上或者@ApiImplicitParams里。给方法入参增加说明 | @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") |
| @ApiImplicitParams | 用在Controller方法上。给方法入参增加说明 | @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") }) |
| @ApiParam | 可用在Controller方法、参数、属性上。 |
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) |
| @ApiResponse | 用在controller的方法上或者@ApiResponses里 | @ApiResponse(code = 400, message = "Invalid user supplied") |
| @ApiResponses | 用在controller的方法上 | @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"), @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"), @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") }) |
| @ResponseHeader | 用在controller的方法上 |
@ResponseHeader(name="head1",description="response head conf") |
| @ApiModel | 用在返回对象类上 | @ApiModel |
| @ApiModelProperty | 用在返回对象类的属性 |
@ApiModelProperty(notes = "错误消息") |
@ApiImplicitParam
|
属性 |
取值 |
作用 |
|
paramType |
|
查询参数类型 |
|
|
path |
以地址的形式提交数据 |
|
|
query |
直接跟参数完成自动映射赋值 |
|
|
body |
以流的形式提交 仅支持POST |
|
|
header |
参数在request headers 里边提交 |
|
|
form |
以form表单的形式提交。仅支持POST |
|
dataType |
|
参数的数据类型 只作为标志说明，并没有实际验证 |
|
|
Long |
|
|
|
String |
|
|
name |
|
接收参数名 |
|
value |
|
接收参数的意义描述 |
|
required |
|
参数是否必填 |
|
|
true |
必填 |
|
|
false |
非必填 |
|
defaultValue |
|
默认值 |
Content Type
其他网址
HTTP系列--Content type_feiying0canglang的博客-CSDN博客