集成Swagger

Swagger簡介

Swagger是一個規范且完整的框架，用于生成、描述、呼叫和可視化 RESTful風格的 Web 服務，

Swagger的目標是對 REST API 定義一個標準且和語言無關的介面，可以讓人和計算機擁有無須訪問原始碼、檔案或網路流量監測就可以發現和理解服務的能力，當通過 Swagger進行正確定義，用戶可以理解遠程服務并使用最少實作邏輯與遠程服務進行互動，與為底層編程所實作的介面類似，Swagger消除了呼叫服務時可能會有的猜測，

Swagger 的優勢

• 支持 API 自動生成同步的在線檔案：使用 Swagger 后可以直接通過代碼生成檔案，不再需要自己手動撰寫介面檔案了，對程式員來說非常方便，可以節約寫檔案的時間去學習新技術，
• 提供 Web 頁面在線測驗 API：光有檔案還不夠，Swagger 生成的檔案還支持在線測驗，引數和格式都定好了，直接在界面上輸入引數對應的值即可在線測驗介面，

springboot集成Swagger

1、新建一個springboot專案，添加web框架

2、添加相關依賴

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

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

3、撰寫controller層

package com.kuang.swagger.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

撰寫Swagger的配置類4、撰寫Swagger的配置類

package com.kuang.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2    //開啟Swagger
public class SwaggerConfig {

}

###5、測驗運行，輸入：http://localhost:8080/swagger-ui.html 進入到頁面

配置Swagger資訊

Swagger 是通過注解的方式來生成對應的 API，在介面上我們需要加上各種注解來描述這個介面

1、撰寫Swagger配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        //作者資訊
        Contact contact = new Contact("張三", "http://localhost:8080", "963330213@qq.com");
        return new ApiInfo(
                "張三的Swagger檔案",    //名字
                "即使再小的帆也能遠航",  //座右銘
                "1.0",                 //版本號
                "http://localhost:8080",//作者連接
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

###2、啟動測驗

配置Swagger掃描介面

1、配置掃描的介面

//配置了Swagger的Docket的bean實體
@Bean
public Docket docket(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors：配置要掃描的api方式
            //basePackage：指定包掃描(常用)
            //any()：掃描全部
            //none()：不掃描
            //withClassAnnotation：掃描類上的注解
            //withMethodAnnotation：掃描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
            .paths(PathSelectors.ant("/study/**"))//過濾路徑,只掃描帶有study請求的介面
            .build();
}

運行測驗：因為配置了只掃描 study請求下的介面，所以顯示沒有被定義的注解

2、配置是否啟動Swagger

//配置了Swagger的Docket的bean實體
@Bean
public Docket docket(Environment environment){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())

            .enable(false)  //是否啟動Swagger，如果為false，則Swagger不能在瀏覽器中訪問

            .select()
            .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
            //.paths(PathSelectors.ant("/study/**"))//過濾路徑,只掃描帶有study請求的介面
            .build();
    }

Swagger配置多環境

1、新建application-dev.properties

# 應用名稱
spring.application.name=swagger-demo
# 應用服務 WEB 訪問埠
server.port=8081

新建application-dev.properties

# 應用名稱
spring.application.name=swagger-demo
# 應用服務 WEB 訪問埠
server.port=8082

2、撰寫application.properties

# 應用名稱
spring.application.name=swagger-demo
# 應用服務 WEB 訪問埠
server.port=8080

spring.profiles.active=dev #選擇dev環境

3、撰寫Swagger配置類

4、運行測驗

Swagger配置api檔案分組

配置多個分組，多個Docket實體

1、撰寫Swagger配置類,添加多個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組");
}

2、運行測驗

物體類配置

1、添加物體類

package com.kuang.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用戶物體類")
public class User {
    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;
}

2、撰寫controller

package com.kuang.swagger.controller;

import com.study.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "用戶管理") //模塊名稱
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    @ApiOperation("查詢用戶")//給介面添加注釋
    //@ApiImplicitParam(name = "id",value = "用戶編號",required = true) 假設有引數可以設定 引數，引數名稱，是否必傳引數
    public User user(){
        return new User();
    }

    @GetMapping("/hello2")
    @ApiOperation("hello2   方法")//給介面添加注釋
    public String hello(@ApiParam("用戶名") String username){
        return "hello"+username;
    }
}

3、測驗

Swagger測驗介面

分類: [Springboot]