java Swagger 使用匯總

大树2發表於2024-04-20
JavaSwagger

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，提供執行速度和介面安全

相關文章