簡簡單單Swagger,普普通通Swagger

Swagger

談一談歷史

前後端分離

現在的主流解決方案是Vue + SpringBoot

後端時代: 前端只用管理靜態頁面(html) 後端負責渲染,利用模板引擎(jsp) 後端是主力

前後端分離時代:

• 後端: 後端控制層(Controller), 服務層(Service), 數據訪問層(Dao)
• 前端: 前端控制層, 視圖層
  • 僞造後端數據, json.已經存在了,不需要後端,前端依舊能夠跑起來.
• 前端如何交互? ===>API接口
• 前後端相互獨立,鬆耦合;
• 前後端可以部署在不同的服務器上

產生的問題:

• 前後端集成聯調,前端人員和後端人員無法做到及時協商, 儘早解決. 最終導致問題集中爆發;

解決方案:

• 指定Schema[計劃,或者提綱],實時更新最新我的API,降低集成的風險;
• 早些年:指定word計劃文檔;
• 前後端分離:
  • 前端測試後端接口: postman
  • 後端提供接口,需要實時更新最新的消息及改動!

Swagger誕生了!

• 號稱世界上最流行的API框架
• RestFul API文檔在線自動生成工具---->API文檔與API定義同步更新
• 直接運行,可以在線測試API
• 支持多種語言(java,PHP)

官網: https://swagger.io/

在項目中使用swagger需要springfox;

• swagger2
• ui

Springboot集成Swagger

新建一個springboot-web項目

超快!aliyun牛逼!

導入相關依賴

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

編寫Hello工程

配置Swagger—>config

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

測試運行

訪問 http://localhost:8080/swagger-ui.html

可以看到

配置Swagger

swagger的bean實例Docket;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	.select();
    }

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("康袁", "https://blog.csdn.net/qq_41385887", "[email protected]");

        return new ApiInfo(
                "KK的SwaggerAPI文檔",
                "衝就完事兒了",
                "v1.0",
                "https://blog.csdn.net/qq_41385887",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

Swagger 配置掃描接口

Docket.select()

//配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        /**
         * RequestHandlerSelectors,配置要掃描接口的方式
         * basePackage:指定要掃描的包
         * any():掃描全部
         * none():都不掃描
         * withClassAnnotation: 掃描類上的註解,參數是一個註解的反射對象
         * withMethodAnnotation: 掃描方法上的註解
         * paths: 過濾什麼路徑
         * 此處只掃描帶有ky下面請求的接口,我們的Controller中沒有定義,所以什麼swaggerui上什麼都不會顯示
         */
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ky.swagger.controller"))
            	.paths(PathSelectors.ant("/ky/**"))		
                .build();
    }

配置是否啓用Swagger

 //配置了Swagger的Docket的bean實例
     @Bean
     public Docket docket(){
         
     	return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(false)	 //enable:是否啓用Swagger,如果爲false,則Swagger不能在瀏覽器中訪問
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.ky.swagger.controller"))
         .build();
 }    

我只希望我的Swagger在開發環境中使用,在生產環境中不使用

• 定義不同的properties配置文件

• 判斷是不是生產環境 flag = false

• 注入enable(flag)

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8081

application-release.properties

server.port=8082

配置Docket

 //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){
        //設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("dev","test");
        //通過environment.acceptsProfiles(profiles)判斷是否處在自己設定的環境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)   //監聽flag.如果爲true則開啓swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ky.swagger.controller"))
                .build();
    }

配置API文檔的分組

.groupName("ky")

如何配置多個組?

配置多個Docket實例即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }


    //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){
        //設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("dev","test");
        //通過environment.acceptsProfiles(profiles)判斷是否處在自己設定的環境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("ky")
                .enable(true)   //監聽flag.如果爲true則開啓swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ky.swagger.controller"))
                .build();
    }

運行結果

實體類配置

只要我們的接口中,返回值中存在實體類,他就會被掃描到Swagger中

//在Controller中加一個方法
//只要我們的接口中,返回值中存在實體類,他就會被掃描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }

註釋信息

//@Api(註釋信息)
@ApiModel("用戶實體類")
public class User {

    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;

}

顯示結果

Swagger的用處?

• 我們可以通過Swagger給一些比較難理解的屬性或者接口， 增加註釋信息
• 接口文檔實時更新
• 可以在線測試

基本上就是這麼用的,當然如果想在Execute的時候輸入參數測試,Controller中的方法中也必須定義入參纔可以

總結

1. 我們可以通過Swagger給一-些比較難理解的屬性或者接口， 增加註釋信息
2. 接口文檔實時更新
3. 可以在線測試

Swagger是一個優秀的工具，幾乎所有大公司都有使用它

注意

在正式發佈的時候，關閉Swagger! ! !

出於安全考慮,並且也能節省內存.