Swagger学习小记

Swagger学习

1. 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务.

官网：swagger.io

2. Swagger使用

2.1 导入jar包：swagger2、ui /导入依赖

   <dependencies>
                 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
                 <dependency>
                     <groupId>io.springfox</groupId>
                     <artifactId>springfox-swagger2</artifactId>
                     <version>3.0.0</version>
                 </dependency>
         
                 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
                 <dependency>
                     <groupId>io.springfox</groupId>
                     <artifactId>springfox-swagger-ui</artifactId>
                     <version>3.0.0</version>
                 </dependency>
    </dependencies>

2.2开启swagger

```java

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

}
```
swagger version2直接访问swagger-ui
http://localhost:8080/swagger-ui.html

  swagger version3.0需要添加并访问[swagger-ui](http://localhost:8080/swagger-ui/index.html)

http://localhost:8080/swagger-ui/index.html

     <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-boot-starter</artifactId>
         <version>3.0.0</version>
     </dependency>

2.3 配置swagger信息

       //配置swagger的bean实例
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
       }
   
       //apiInfo信息
       public ApiInfo apiInfo(){
           Contact contact = new Contact("", "", "");
           return new ApiInfo("Api Documentation", "Api Documentation", 
                   "1.0", 
                   "urn:tos",
                   contact,
                   "Apache 2.0",
                   "http://www.apache.org/licenses/LICENSE-2.0",
                   new ArrayList());
       }

2.4.配置swagger扫描接口

使用Docket的select()方法链式函数

在Docket的bean中添加select()方法等如下：

       //配置swagger的bean实例
       @Bean
       public Docket docket(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
       //        RequestHandlerSelectors：配置要扫描的方式 
       //        1.basePackage()：扫描指定包
       //        2.any()：扫描全部
       //        3.none()：不扫描
       //        4.withMethodAnnotation()：扫描方法上的注解
       //        5.withClassAnnotation()：扫描类上的注解
                   .apis(RequestHandlerSelectors.basePackage("com.li.swaggerstudy.controller")).
       //过滤路径--正则表达式
                   .paths(PathSelectors.ant(""))
                   .build();
       }

           //获取项目环境
           Profiles profiles = Profiles.of("dev");
           boolean flag = environment.acceptsProfiles(profiles);
           

2.5 swagger配置分组,多个分组使用多个Docket

                   .groupName("li")

2.6 swagger扫描实体类

1. 使用@ApiModel("实体类名")
2. RestController方法返回实体类
3. 使用@Api 等价于@ApiModel
4. @ApiOperation 方法注释

3. 总结

1. 能给比较难理解的属性和接口，增加注释信息。
2. 接口文档实时更新
3. 可以在线测试

在发布时候关闭swagger文档，以减少运行内存与保证安全。