1.引入配置
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <parent> <artifactId>learn-parent</artifactId> <groupId>com.liupei</groupId> <version>0.0.1-SNAPSHOT</version> </parent> <modelVersion>4.0.0</modelVersion> <artifactId>learn-swagger</artifactId> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!--引入swagger ui包--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency> </dependencies> </project>
2.配置config
package com.liupei.common.config; import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; /** * TODO * * @author liu pei * @version 1.0 * @date 2020/10/16 9:14 */ @Configuration @EnableSwagger2 @EnableSwaggerBootstrapUI public class Swagger2Configuration { /** * 用户中心模块 * @return */ @Bean public Docket sys() { return new Docket(DocumentationType.SWAGGER_2) .groupName("莹尾狐科学-用户中心") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.liupei.sys.controller")) .paths(PathSelectors.any()) .build(); } /** * 投诉管理 模块 * @return */ /* @Bean public Docket createComplaintRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("投诉管理") .select() .apis(RequestHandlerSelectors.basePackage("com.liupei.sys.controller")) .paths(PathSelectors.any()) .build(); } */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("莹尾狐科学 API") .description("莹尾狐科学做的小程序 RESTful APIs") .termsOfServiceUrl("http://127.0.0.1:9002/doc.html") .contact( new Contact("刘佩","http://127.0.0.1:9002/doc.html","3268707800@qq.com")) .version("1.0") .build(); } /** * 认证配置 * @return */ private List<Parameter> parameter() { List<Parameter> params = new ArrayList<Parameter>(); params.add(new ParameterBuilder().name("token") .description("认证令牌") .modelRef(new ModelRef("string")) .parameterType("header") .required(false).build()); return params; } }
3.实体
package com.liupei.sys.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; /** * TODO * * @author liu pei * @version 1.0 * @date 2020/10/16 11:11 */ @ApiModel(value = "用户实体",description = "提供用户信息") public class SysUser implements Serializable { @ApiModelProperty(value = "用户ID" ) private Integer id; @ApiModelProperty(value = "用户名") private String name; @ApiModelProperty(value = "邮件") private String email; public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } }
4.配置文件
# server server.port=9002 server.tomcat.basedir=/. #线上环境开启后屏蔽所有Swagger2的资源 #swagger.production=true swagger.basic.enable=true ##swagger Basic认证用户名 swagger.basic.username=liupei ##swagger Basic认证密码 swagger.basic.password=123 #logback logging.config=classpath:logback-spring.xml logging.file=D:/logs/ccb-api.log
----------------------------------------------------完毕--------------------------------------------------
Swagger2 最全注解说明
文章目录
1,swagger2 注解整体说明
2,@API: 请求类的说明
3,@ApiOperation: 方法的说明
3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明
4,@ApiResponses,@ApiResponse: 方法返回值的说明
5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息
5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义
1,swagger2 注解整体说明
用于 controller 类上:
注解 | 说明 |
@Api | 对请求类的说明 |
用于方法上面 (说明参数的含义):
注解 | 说明 |
@ApiOperation | 方法的说明 |
@ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 |
用于方法上面 (返回参数或对象的说明):
注解 | 说明 |
@ApiResponses、@ApiResponse | 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明 |
对象类:
注解 | 说明 |
@ApiModel | 用在 JavaBean 类上,说明 JavaBean 的 用途 |
@ApiModelProperty | 用在 JavaBean 类的属性上面,说明此属性的的含议 |
2,@API: 请求类的说明
@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.
- tags="说明该类的作用"
- value="该参数没什么意义, 所以不需要配置"
示例:
- @API(tags="订单模块")
- @Controller
- public class OrderController {
- }
@API 其它属性配置:
属性名称 | 备注 |
value | url 的路径值 |
tags | 如果设置这个值、value 的值会被覆盖 |
description | 对 api 资源的描述 |
basePath | 基本路径 |
position | 如果配置多个 Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为 true ,将在文档中隐藏 |
3,@ApiOperation: 方法的说明
- @ApiOperation:"用在请求的方法上, 说明方法的作用"
- value="说明方法的作用"
- notes="方法的备注说明"
3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明
@ApiImplicitParams: 用在请求的方法上, 包含一组参数说明
@ApiImplicitParam: 对单个参数的说明
name: 参数名
value: 参数的汉字说明, 解释
required: 参数是否必须传
paramType: 参数放在哪个地方
. header --> 请求参数的获取:@RequestHeader
. query --> 请求参数的获取:@RequestParam
. path(用于 restful 接口)--> 请求参数的获取:@PathVariable
- . body(请求体)--> @RequestBody User user
- . form(普通表单提交)
dataType: 参数类型, 默认 String, 其它值 dataType="Integer"
defaultValue: 参数的默认值
示列:
- @API(tags="用户模块")
- @Controller
- public class UserController {
- @ApiOperation(value="用户登录",notes="随边说点啥")
- @ApiImplicitParams({
- @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
- @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
- @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
- })
- @PostMapping("/login")
- public JsonResult login(@RequestParam String mobile, @RequestParam String password,
- @RequestParam Integer age){
- //...
- return JsonResult.ok(map);
- }
- }
4,@ApiResponses,@ApiResponse: 方法返回值的说明
@ApiResponses: 方法返回对象的说明
@ApiResponse: 每个参数的说明
code: 数字, 例如 400
message: 信息, 例如 "请求参数没填好"
response: 抛出异常的类
示例:
- @API(tags="用户模块")
- @Controller
- public class UserController {
- @ApiOperation("获取用户信息")
- @ApiImplicitParams({
- @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户 Id")
- })
- @ApiResponses({
- @ApiResponse(code = 400, message = "请求参数没填好"),
- @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
- })
- @ResponseBody
- @RequestMapping("/list")
- public JsonResult list(@RequestParam String userId) {
- ...
- return JsonResult.ok().put("page", pageUtil);
- }
- }
5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息
@ApiModel: 用于 JavaBean 的类上面, 表示此 JavaBean 整体的信息
(这种一般用在 post 创建的时候, 使用 @RequestBody 这样的场景,
请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )
5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义
示例:
- @ApiModel(description= "返回响应数据")
- public class RestMessage implements Serializable{
- @ApiModelProperty(value = "是否成功")
- private boolean success=true;
- @ApiModelProperty(value = "返回对象")
- private Object data;
- @ApiModelProperty(value = "错误编号")
- private Integer errCode;
- @ApiModelProperty(value = "错误信息")
- private String message;
- /* getter/setter 略 */
- }