Swagger 3.0與SpringBoot 2.6.1集成

世界上最流行的Api框架
RestFul Api文檔在線自動生成工具=>Api文檔與Api定義同步更新
直接運行，可以在線測試Api接口(controller（RequestMapping）)
Swagger官網https://swagger.io/

1. 在項目中使用Swagger需要導入jar包

springBox-swagger2
springBox-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>
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</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>

2. 編寫一個Controller

@RestController
public class HelloController {

    // /error默認請求
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

主啟動類需添加@EnableOpenApi注解

@EnableOpenApi
@SpringBootApplication
public class Springboot09SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run (Springboot09SwaggerApplication.class, args);
    }

}

3. 配置SwaggerConfig

@Configuration
//開啟Swagger2
@EnableSwagger2
public class SwaggerConfig{
//RequestHandlerSelectors)配置掃描接口的方式
    /*RequestHandlerSelectors.basePackage("com.ji.controller"):指定掃描的包
      RequestHandlerSelectors.any() 掃描全部
      RequestHandlerSelectors.none() 不掃描
      RequestHandlerSelectors.withClassAnnotation(RestController.class) 掃描類上的注解    @Target(ElementType.TYPE)
      RequestHandlerSelectors.withMethodAnnotation (GetMapping.class) 掃描方法上的注解  @Target(ElementType.METHOD)
    * */

    //paths :過濾什么路徑
    //配置SwaggerDocket Bean實例

    //配置
    @Bean
    public Docket docket(Environment environment){
        //多環境 開關swagger  environment
        //設置要顯示swagger 的環境
        Profiles profiles=Profiles.of ("dev","test");
        //判斷當前環境是否是profiles中顯示swagger的環境
        boolean b = environment.acceptsProfiles (profiles);


        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("jsp")   //配置Api文檔分組   多個Docket分組
                .enable (b)   //是否啟動swagger 如果為false則swagger不能再瀏覽器中訪問
                .select ()
                .apis (RequestHandlerSelectors.basePackage("com.ji.controller"))
                .paths (PathSelectors.ant ("/ji/**"))
                .build ();
    }
    @Bean
    public Docket docket1(){
        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("hcy");   //配置Api文檔分組
    }
    @Bean
    public Docket docket2(){
        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("zzz");   //配置Api文檔分組
    }
    //配置swagger信息
    private ApiInfo apiInfo(){
        return new ApiInfo ("Jsp SwaggerLogger",
                "學習",
                "17.0",
                "https://www.cnblogs.com/Liuyunsan/",
                new Contact ("jsp", "https://www.cnblogs.com/Liuyunsan/", "[e-mail]"),   //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList ());
    }
}

4. Models

@RestController
public class HelloController {
    //Operation接口  給controller 方法增加注釋
    @ApiOperation ("helloController控制類")
    // /error默認請求
    @GetMapping(value = "/ji/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping(value = "/ji/hello")
    //只要我們的接口中，返回值張存在實體類，它就會被掃描到swagger中
    public User user(@ApiParam("用戶名") String username){
        return new User();
    }


}

//@Api("注釋")
@ApiModel("用戶實體類")
public class User {
    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;
}

5. 總結

• 可以通過Swagger給比較難理解的屬性或者接口，增加注釋信息
• 接口文檔實時更新
• 可以在線測試
• 正式發布時，需要關閉Swagger（出於安全考慮和性能考慮）