一、Swagger简介

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务。

接口文档对于前后端开发人员都非常重要。Swagger可以使得接口文档动态生成

OpenApi：是REST API的api描述格式

  • 每个访问地址类型。POST（写）或者GET（读）
  • 每个操作的参数，包括输入输出参数
  • 认证方法
  • 连接信息，声明，使用团队和其他信息。

Open API规范可以使用YAML或JSON格式进行编写。

Open API规范为REST API定义了一个与语言无关的标准接口。

Swagger2的组件：

  • Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。配置中出现->定制文档
  • Swagger UI：将Open API规范呈现为交互式API文档，用可视化UI展示描述文件。
  • Swagger Codgen：将Open API规范生成为服务器存根和客户端库。
  • Swagger Inspector：跟ui有点类似，但是可以返回更多信息，也可以保存请求的实际参数数据。
  • Swagger Hub：集成上面所有项目的各个功能。

spring fox：是根据代码生成接口文档，所以生成进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。

二、Swagger-UI用法

1
2
3
4
5
6
7
8
9
10
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在启动类上添加一个注解

1
2
@EnableSwagger2 //springfox的注解，开启swagger2相关技术的开启
//会扫描当前类所在的包以及子包中所有类型当中的注解。做swagger文档的定值

可以通过 localhost:8080/swagger-ui.html来访问swagger文档

swagger-ui可以帮我们做请求的模拟处理（类似于postman）

三、Swagger2配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@Configuration
public class SwaggerConfig {
    /**
     * 创建Docket类型的对象，并使用spring容器管理
     * Docket是Swagger的全局配置对象
     *
     * @return
     */
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
		//1.api帮助文档的描述信息
        ApiInfo apiInfo =  //api帮助文档的描述信息
                new ApiInfoBuilder()
                        .contact(new Contact("lqSwagger开发文档",  //文档的发布者名称
                                "http://localhost.com", //企业网站
                                "1426768270@qq.com")) //发布者的电子邮箱
                        .title("Swagger框架学习帮助文档")
                        .description("Swagger框架学习帮助文档详细描述")
                        .version("1.2")
                        .build(); //构建器模式创建对象
        docket.apiInfo(apiInfo);//给docket上下文配置api描述信息
        docket
                .select() //2.获取Docket中的选择器 返回ApiSelectorBuilder.构建选择器 如：扫描什么包的注解
                .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))//3.设定扫描那个包（包含子包）中的注解
                .apis(Predicates.not(//取反
                        RequestHandlerSelectors.withMethodAnnotation( //当方法上有什么注解的时候返回true
                                MyAnnotationSwagger.class)) //自定义的注解
                )//4.整体表示方法上有这个注解的时候就不会生成文档在swagger上面了
                .paths(Predicates.or(
                        PathSelectors.regex("/swagger/.*"),
                        PathSelectors.regex("/.*"),
                        PathSelectors.regex("/swagger2/.*"))
                )//5.通过正则表达式约束生成api文档的路径地址  表示上面三个路径的任意一个都会返回true，也就是会在swagger文档中表现出来
                .build();//6.必须要build，要不然上面不会生效
        return docket;
    }
}

自定义的注解类：

1
2
3
4
5
6
7
@Target(value = {ElementType.METHOD,ElementType.TYPE}) //描述当前的注解可以定义在什么资源上面
//METHOD：方法  TYPE：类型 FILED：属性 PARAMETER：定义在方法参数上
@Retention(RetentionPolicy.RUNTIME) //当前注解什么时候有效
//RUNTIME：运行时有效 SOURCE：源码有效 CLASS：字节码有效
public @interface MyAnnotationSwagger {
    String value() default "";//自定义注解的属性
}

四、Swagger2常用注解

  • @Api：描述当前类型生成帮助文档的信息

    tags属性其实就是给控制类起别名，在swagger上显示是别名（可以用中文），定义几个在ui中就显示几个。

    1
    2
    3
    @RestController
    @Api(tags = "Swagger学习控制器") //起别名
    public class MyController {}

  • @ApiOperation：给方法描述 value没有默认

    1
    2
    3
    4
    5
    @ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求方法")
    @PostMapping("/post")
    public String post(){
        return "post";
    }

  • @ApiParam

    1
    2
    3
    4
    5
    6
    @ApiOperation(value = "post方法，执行数据新增操作",notes = "Swagger学习使用-处理POST请求方法")
        @PostMapping("/post")
        public String post(@ApiParam(name = "用户名",value = "新增用户时提供的用户名",required = true) String username,
                           @ApiParam(name = "密码",value = "新增用户时提供的密码",required = true) String password){
            return "post";
        }

  • @ApiIgnore ：忽略，当前注解描述的方法或者类型，不生成api帮助文档。

    1
    2
    3
    4
    5
    @ApiIgnore
    @GetMapping("/get")
    public  String get(){
        return "get";
    }

  • @ApiImplicitParam：对方法的参数进行描述

    1
    2
    3
    4
    5
    @GetMapping("/test")
    @ApiImplicitParam(name = "a",value = "test方法的参数a的描述",required = false,paramType = "字符串",dataType = "名值对")
    public String test(String a,String b){
        return "test";
    }

  • @ApiModel：描述一个实体类型，当该实体类型会成为api帮助问你当方法的返回值类型的时候，则次注解会被解析。

    @ApiModelProperty：对实体类的属性进行描述

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    @ApiModel(value = "用户类实体",description = "存储用户数据")
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class User {
        @ApiModelProperty(value = "主键",name = "主键（id）",required =false,example = "1",hidden = false)
        private Integer id;
        private String username;
        private String password;
    }