java Swagger 使用汇总

Swagger

1.Swagger 简介

• 最流行的api框架
• restful api在线自动生成工具： api文档与api定义同步更新
• 直接运行，可以在线测试api接口
• 支持多种语言：java,php

2.官网 https://swagger.io

在项目中使用swagger需要springbox

• swagger2
• ui

3.SpringBoot集成Swagger

https://mvnrepository.com -->springfox-swag

1.新建项目

2.添加依赖到pom.xml

• springfox-swagger2
• springfox-swagger-ui

<!-- 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>

3.添加配置文件Swagger==> Config

@Configuartion
@EnableSwagger2  //开启swagger2
public class SwaggerConfig{
    
   //配置了swagger的docket的bean实例
    @Bean
    public Docket dockert(){
        
        
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()
            .select()
                     //RequestHandlerSelectors 配置要扫描接口的方式
                     //basePackage 指定要扫描的包
            .apis(RequestHandlerSelectors.basePackage("com.xxpage.controller"))
                    //paths() 过滤路径
            .paths(PathSelectors.ant("/chen/**")) 
            .build();
    }
    
    private ApiInfo apiInfo(Environment environment){
        //设置要显示的swagger环境
         Profiles profiles=Profiles.of("dev","test");
        //通过environment判断是否处在自己设定的环境中
         boolean flag=environment.acceptsProfiles(profiles)
        
        Contact contact=new Contact("chen","http://blog.xx.com","59888745@qq.com");
        
        return new ApiInfo(
          title:"xxx项目的swagger api 文档"，
          description:"xx",
          version:"v1.0",
          .enable(flag),  //是否启用swagger fasle
          termsOfServiceUrl:"https://blog.xxx.com",
          contact,
          license:"Apache 2.0",
          licenseUrl:"http://www.apache.org",
          new ArraList()
        );
    }
}

4.配置swagger

 return new ApiInfo(
          title:"xxx项目的swagger api 文档"，
          description:"xx",
          version:"v1.0",
          .enable(flag),  //是否启用swagger fasle
          .groupName("api1.0")
          termsOfServiceUrl:"https://blog.xxx.com",
          contact,
          license:"Apache 2.0",
          licenseUrl:"http://www.apache.org",
          new ArraList()
        );

5.配置swagger扫描接口

   //RequestHandlerSelectors 配置要扫描接口的方式
                     //basePackage 指定要扫描的包
            .apis(RequestHandlerSelectors.basePackage("com.xxpage.controller"))

6.配置api文档的分组

.groupName("api1.0")

7.配置多个api文档分组:多个Docket实例即可

  @Bean
    public Docket dockert(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("api1.0")；
    }
   
  @Bean
    public Docket dockert2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("api21.0")；
    }

  @Bean
    public Docket dockert3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("api3.0")；
    }

8.配置API方法，参数的接口说明,生成swagger文档时有对应的中文说明

@ApiOperation("xxx控制类")
@GetMapping("/user")
public String user(@ApiParam("用户名") String username){
       return "hello";
}

4.swagger总结

1. 可以通过swagger给接口，参数添加注释，方便测试人员理解
2. 接口文档实时更新，不用另外发时间写一套接口文档
3. 可以在线测试，发表了接口就有了swagger接口文档
4. 在正式发布的时间，关闭swagger，提供运行速度和接口安全