世界上最流行的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/", "[email protected]"),   //作者資訊
                "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（出於安全考慮和效能考慮）