Swagger

1.什么是Swagger？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述 文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个 描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文 档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型 紧密集成到服务器端的代码，允许API来始终保持同步。

2.Swagger的作用：

• 接口的文档在线自动生成
• 功能测试

3.Swagger的使用：

1. 导入相关依赖

   
   
       io.springfox
       springfox-swagger2
       2.9.2
   
   
   
   
       io.springfox
       springfox-swagger-ui
       2.9.2
   
   

2. 启动类中添加@EnableSwagger2注解：@EnableSwagger2是springfox提供的注解，代表Swagger2相关技术的开启，会扫描所在包，以及子包中所有的类型的注解，做swagger文档的定值。

3. 写一个api接口

   @RestController
   public class HelloController {
       
       @GetMapping("/get")
       public String get() {
           return "get";
       }
       
       @PostMapping("/post")
       public String post() {
           return "post";
       }
       
       @RequestMapping("/hello")
       public String hello() {
           return "hello";
       }
   }
   

4. Swagger的基础信息配置控制类

   @Configuration
   @EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加
   public class SwaggerConfig {
   
       // 创建swagger bean
       @Bean
       public Docket docket() {
           // Docket是swagger全局配置对象
           // DocumentationType：指定文档类型为swagger2
           return new Docket(DocumentationType.SWAGGER_2)
                   // swagger信息
                   .apiInfo(apiInfo());
       }
   
       // swagger文档信息
       public ApiInfo apiInfo() {
           // 作者信息
           Contact contact = new Contact(
                   // 文档发布者的名称
                   "iqiuq",
                   // 文档发布者的网站地址
                   "https://iqiuq.gitee.io/qiuqblogs/",
                   // 文档发布者的电子邮箱
                   "[email protected]"
           );
           return new ApiInfo(
                   // 标题
                   "iqiuq swagger api",
                   // 文档描述
                   "演好自己人生的剧本",
                   // 版本号
                   "1.0",
                   // 服务组url地址
                   "urn:tos", 
                   // 作者信息
                   contact,
                   // 开源组织
                   "Apache 2.0",
                   // 开源地址
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   // 集合
                   new ArrayList()
           );
       }
   }
   

   Swagger扫描包配置

   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   
       // 创建swagger bean
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2)
                   // swagger信息
                   .apiInfo(apiInfo())
                   // swagger 扫描包配置
                   // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解
                   .select()
                   /**
                    * requestHandlerSelectors：请求处理选择器
                    * basePackage()：扫描指定包下的所有接口
                    * any()：扫描所有的包
                    * none()：不扫描
                    * withClassAnnotation()：扫描指定类上的注解，参数是一个注解的放射对象
                    * withMethodAnnotation()：扫描方法上的注解
                    */
                   // 指定扫描器扫描的规则（断言）
                   .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                   /**
                    * pathSelectors：路径选择器，过滤路径
                    * ang()：选择所有路径
                    * none()：都不选择
                    * ant()：选择指定路径
                    * regex()：正则表达式
                    */
                   .paths(PathSelectors.regex("/hello"))
                   .build();
       }
           return new ApiInfo(
                   // 标题
                   "iqiuq swagger api",
                   // 文档描述
                   "演好自己人生的剧本",
                   // 版本号
                   "1.0",
                   // 服务组url地址
                   "urn:tos", 
                   // 作者信息
                   contact,
                   // 开源组织
                   "Apache 2.0",
                   // 开源地址
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   // 集合
                   new ArrayList()
           );
   }
   

    配置是否开启swagger

   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   
       // 创建swagger bean
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2)
                   // swagger信息
                   .apiInfo(apiInfo())
                   // 配置是否开启swagger，若为false，则浏览器不能访问
                   .enable(false);
       }
   
       // swagger文档信息
       public ApiInfo apiInfo() {
           // 作者信息
           Contact contact = new Contact(
                   "iqiuq",
                   "https://iqiuq.gitee.io/qiuqblogs/",
                   "[email protected]");
           return new ApiInfo(
                   "iqiuq swagger api",
                   "演好自己人生的剧本",
                   "1.0",
                   "urn:tos", contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList());
       }
   }
   

   开发和测试环境中开启swagger，其他环境不开启

   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   
       // 创建swagger bean
       @Bean
       public Docket docket(Environment environment) {
           // 配置swagger的docket的bean实例
           Profiles profiles = Profiles.of("dev","test");
           // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .enable(flag)
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                   .paths(PathSelectors.regex("/hello"))
                   .build();
       }
   
       // swagger文档信息
       public ApiInfo apiInfo() {
           Contact contact = new Contact(
                   "iqiuq",
                   "https://iqiuq.gitee.io/qiuqblogs/",
                   "[email protected]");
           return new ApiInfo(
                   "iqiuq swagger api",
                   "演好自己人生的剧本",
                   "1.0",
                   "urn:tos", 
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList());
       }
   }
   

   swagger分组配置

   每个组就是一个docket实例，多个组就是创建多个docket的实例

   @Configuration
   @EnableSwagger2 //开启swagger2
   public class SwaggerConfig {
   
       // 创建swagger bean
       @Bean
       public Docket docket1(Environment environment) {
           // 配置swagger的docket的bean实例
           Profiles profiles = Profiles.of("dev","test");
           // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   // swagger信息
                   .apiInfo(apiInfo())
                   // 配置是否开启swagger，若为false，则浏览器不能访问
                   .enable(flag)
                   // 配置组名
                   .groupName("iqiuq")
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                   .paths(PathSelectors.regex("/hello"))
                   .build();
       }
   
       @Bean
       public Docket docket2(Environment environment) {
           Profiles profiles = Profiles.of("dev","test");
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .enable(flag)
                   .groupName("哈哈哈")
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                   .paths(PathSelectors.regex("/hello"))
                   .build();
       }
   
       @Bean
       public Docket docket3(Environment environment) {
           Profiles profiles = Profiles.of("dev","test");
           boolean flag = environment.acceptsProfiles(profiles);
   
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .enable(flag)
                   .groupName("嘻嘻嘻")
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                   .paths(PathSelectors.regex("/hello"))
                   .build();
       }
       // swagger文档信息
       public ApiInfo apiInfo() {
           Contact contact = new Contact(
                   "iqiuq",
                   "https://iqiuq.gitee.io/qiuqblogs/",
                   "[email protected]");
           return new ApiInfo(
                   "iqiuq swagger api",
                   "演好自己人生的剧本",
                   "1.0",
                   "urn:tos", 
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList());
       }
   

启动项目，并在浏览器输入http://localhost:8080/swagger-ui.html进行swagger-ui界面访问

4.Swagger常用注解：

@Api：是类上注解，控制整个类生成接口信息的内容

1. tags：类的名称，可以有多个值，多个值表示多个副本，在UI视图中就显示几个控制器访问菜单
2. description：描述，已过时

@ApiOperation：方法的说明，value值必须提供

1. value：说明方法的作用
2. notes：方法的备注说明

@ApiIgnore

1. @Apilgnore：忽略，当前注解描述的方法或类型，不生成api文档

@ApiImplicitParam：使用在方法上，描述方法的单个参数

1. name：参数名称
2. value：描述
3. required：是否必要参数
4. paramType：参数类型
5. dataType：数据类型

@ApiImplicitParams：使用在方法上，描述方法的一组参数

1. value：是@ApiImplicitParam类型的数组

@ApiModel：描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档方法的一个返回值类型的时候，此注解被解析

1. value：自定义实体
2. description：详细描述

@ApiModelProperty：实体类属性描述

1. name：字段别名
2. value：字段描述
3. required：是否是必须字段
4. example：示例数据
5. hidden：是否隐藏数据

@ApiResponses：方法返回对象的说明

@ApiResponse：每个参数的说明

1. code：数字，例如：300
2. message：信息，例如：”请求参数没填好"
3. response：抛出异常的类