SpringBoot + Swagger Demo

  Swagger是什麼?

  Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。
  Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就能夠發現和理解服務的能力。當經過Swagger 進行正肯定義，用戶能夠理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口相似，Swagger 消除了調用服務時可能會有的猜想。

  Swagger 的優點

　　1. 支持 API 自動生成同步的在線文檔：使用 Swagger 後能夠直接經過代碼生成文檔，再也不須要本身手動編寫接口文檔了，對程序員來講很是方便，能夠節約寫文檔的時間去學習新技術。

　　2.提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值便可在線測試接

在SpringBoot中集成Swagger是目前的項目主流,這裏就展現一個Demo.

使用教程

1. 使用IDEA建立一個SpringBoot項目

2. 添加依賴(這些依賴中不單單是Swagger的依賴,還有一些經常使用的依賴,一併列出)

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!--Swagger 依賴開始-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.10.0</version>
        </dependency>
        <!--Swagger 依賴結束-->
    </dependencies>

3. 建立SwaggerConfig.java(Swagger的配置類)

@Configuration  //必須存在
@EnableSwagger2  // 必須存在
// 必須存在 掃描的API Controller包
@ComponentScan(basePackages = {"com.yhl.test.swagger.controller" })
public class SwaggerConfig {
    @Bean
    public Docket customDocket(){
        return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    public ApiInfo apiInfo(){
        Contact contact = new Contact("YHL","http://www.ly058.cn/","email");
        return  new ApiInfoBuilder()
                .title("測試Swagger API")
                .description("API接口")
                .contact(contact)
                .version("1.0.1")
                .build();
    }
}

4.建立測試的entity類(@Data是lombok的標籤,在這裏替代getter和setter方法)

@Data
public class User {
    private String username;
    private  String password;

    public User(String username, String password){
        this.username = username;
        this.password = password;
    }
}

5. 建立測試的controller類(爲了方便,沒有鏈接數據庫,使用list替代)

@RestController
@Api(value = "用戶模塊", description = "用戶接口信息")
public class UserController {
    //模擬數據庫
    public static List<User> users = new ArrayList<User>();

    static {
        users.add(new User("張三", "123456"));
        users.add(new User("李四", "123456"));
    }

    //獲取用戶列表
    @ApiOperation(value = "獲取用戶列表", notes = "獲取全部用戶的列表")
    @GetMapping("/users")
    public Object users() {
        Map<String, Object> map = new HashMap<>();
        map.put("users", users);
        return map;
    }

    @ApiOperation(value = "獲取單個用戶", notes = "根據ID查詢某個用戶的信息")
    @ApiImplicitParam(value = "用戶ID", paramType = "path")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable("id") int id) {
        return users.get(id);
    }

    @ApiOperation(value = "添加用戶", notes = "根據傳入的用戶信息添加用戶")
    @ApiImplicitParam(value = "用戶對象", paramType = "query")
    @PostMapping("/user")
    public Object addUser(User user) {
        return users.add(user);

    }

    @ApiOperation(value = "刪除用戶", notes = "根據傳入的用戶ID刪除用戶")
    @ApiImplicitParam(value = "用戶ID",paramType = "path")
    @DeleteMapping("/user/{id}")
    public Object delete(@PathVariable("id") int id) {
        return users.remove(id);
    }

}

6. 結果,訪問http://localhost:8080/swagger-ui.html