Swagger2 初始用

1.结合Spring-Boot 引入 pom 依赖 

 <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger2</artifactId>
             <version>2.9.2</version>
             <exclusions>
                 <exclusion>
                     <artifactId>guava</artifactId>
                     <groupId>com.google.guava</groupId>
                 </exclusion>
             </exclusions>
         </dependency>
         <dependency>
             <groupId>com.google.guava</groupId>
             <artifactId>guava</artifactId>
             <version>28.0-jre</version>
         </dependency>
         <!--界面支持-->
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger-ui</artifactId>
             <version>2.9.2</version>
         </dependency>

pom.xml

2.创建一个 SwaggerConfig 配置类

 1 @Configuration
 2 @EnableSwagger2
 3 public class SwaggerConfig {
 4
 5     @Bean
 6     public Docket createRestApi() {
 7         return new Docket(DocumentationType.SWAGGER_2)
 8                 .select()
 9                 // 方法需要有ApiOperation注解才能生存接口文档
10                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
11                 // 路径使用any风格
12                 .paths(PathSelectors.any())
13                 .build()
14                 // 如何保护我们的Api，有三种验证（ApiKey, BasicAuth, OAuth）
15                 .securitySchemes(security())
16                 // 接口文档的基本信息
17                 .apiInfo(apiInfo());
18     }
19
20     /**
21      * 接口文档详细信息
22      *
23      * @return
24      */
25     private ApiInfo apiInfo() {
26         return new ApiInfoBuilder().title("Swagger2 API").description("xd-api文档").termsOfServiceUrl("http://www.localhost:8080").version("1.0.0").build();
27     }
28
29     private List<ApiKey> security() {
30         ArrayList<ApiKey> apiKeys = new ArrayList<>();
31         apiKeys.add(new ApiKey("token", "token", "header"));
32         return apiKeys;
33     }
34
35 }

3.使用 controller 实例

 @Api(tags = "登录接口")
 @RequestMapping("/api")
 @RestController
 public class ApiLoginController {

     @PostMapping("login")
     @ApiOperation(value = "用户登录接口")
     @ApiImplicitParams({
             @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String"),
             @ApiImplicitParam(name = "password", value = "登录密码", required = true, dataType = "String")
     })
     public String login(String username, String password) {
         return username + " : " + password;

     }

 }

LoginController.java

4.常用注解说明

@Api：修饰整个类，描述Controller的作用 （可选值：value，tags，description...可以自行查看源码）

@ApiOperation：描述一个类的一个方法，或者说一个接口 （用于方法；表示一个http请求的操作 ，value用于方法描述 ，notes用于提示内容）

@ApiParam：单个参数描述 （用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填（默认值为false））

@ApiModel：用对象来接收参数 （用于类 表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略）

@ApiModelProperty：用对象接收参数时，描述对象的一个字段 （用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏）

 @ApiOperation(value = "用户发送邮件操作", httpMethod = "GET", response = String.class, notes = "用户发送邮件操作，提供用户管理-用户发送邮件操作")
 public String sendEmail(@ApiParam ( value = "userId", required = true ) @RequestParam (
                         value = "userId" ) String userId,
                         @ApiParam(name="邮件对象",value="传入json格式",required=true)
                         @RequestBody EmailModel model,
             HttpServletRequest request) {

 -------------------------------------------------------------------------------------------
 @ApiModel(value="邮件对象",description="邮件对象实体类")
 public class EmailModel extends BaseModel {
     //邮件发送人
     @ApiModelProperty(value="邮件发送人",name="sender",example="xxxxx@qq.com")
     private String sender;
     //邮件接收人
     @ApiModelProperty(value="邮件接收人",name="recipients",example="xxxxx@qq.com")
     private String  recipients;
     //邮件主题
     @ApiModelProperty(value="邮件主题",name="recipients")
     private String subject;
     //邮件内容
     @ApiModelProperty(value="邮件内容",name="邮件内容")
     private String text;
  }

代码段

效果图

@ApiIgnore：使用该注解忽略这个API，用于类或者方法上 （用于类或者方法上，可以不被swagger显示在页面上）

@ApiImplicitParam：一个请求参数，用于方法上
name – 参数名称
value – 参数说明
dataType – 数据类型
paramType – 参数类型
example – 举例说明

@ApiImplicitParams：多个请求参数 ，包含多个 @ApiImplicitParam，用于方法上