SpringBoot之Swagger——整合Swagger2

• 1. 新增pom依賴
• 2. 新建Swagger的配置類
• 3. Controller
• 4. 執行結果
• 5. 原始碼下載

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

Swagger2註解說明
@Api()：作用於類上，表示這個類是swagger的資源。
tags = ”說明該類的作用“
@ApiOperation()：用在請求的方法上，說明的方法的使用者和作用
value=“說明方法的用途、作用”
notes="方法的備註說明“
@ApiImplicitParams()：用在請求的方法上，表示一組引數說明，可以包含多個@ApiImplicitParam()
@ApiImplicitParam()：指定一個請求引數的各個方面
name：引數名
value：引數的漢字說明
required：引數是否必須傳
dataType：引數型別
defaultValue：引數的預設值
@ApiResponses()：用在請求的方法上，表示一組響應。可以包含多個@ApiResponse()
@ApiResponse()：用於表示一個錯誤的響應資訊
code：數字
message：資訊
response：丟擲異常的類
@ApiModel()：用在響應類上，表示一個返回響應資料的資訊。
@ApiModelProperty()：用在屬性上，描述響應類的屬性

1. 新增pom依賴

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</
 
artifactId>
	<version>2.9.2</version>
</dependency>

2. 新建Swagger的配置類

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.
 
PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by HuangJun
 * 13:43 2018/11/28
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改為自己的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.springboot.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-api文件")
                .description("API 描述")
                .version("1.0")
               // .contact(new Contact("Y.S.K", "http://ysk521.cn", "[email protected]"))
                .build();
    }

}

3. Controller

import com.springboot.swagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

/**
 * Created by HuangJun
 * 15:02 2018/11/28
 */
@RequestMapping("/user")
@RestController
@Api(value = "user",tags = {"User API"})
public class UserController {

    // 建立執行緒安全的Map
    static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());

    @ApiOperation(value="獲取使用者列表", notes="")
    @GetMapping(value="")
    public List<User> getUserList() {
        // 處理"/users/"的GET請求，用來獲取使用者列表
        // 還可以通過@RequestParam從頁面中傳遞引數來進行查詢條件或者翻頁資訊的傳遞
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    @ApiOperation(value="建立使用者", notes="根據User物件建立使用者")
    @ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
    @PostMapping(value="")
    public String postUser(@RequestBody User user) {
        // 處理"/users/"的POST請求，用來建立User
        // 除了@ModelAttribute繫結引數之外，還可以通過@RequestParam從頁面中傳遞引數
        users.put(user.getId(), user);
        return "success";
    }

    @ApiOperation(value="獲取使用者詳細資訊", notes="根據url的id來獲取使用者詳細資訊")
    @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "String")
    @GetMapping(value="/{id}")
    public User getUser(@PathVariable String id) {
        // 處理"/users/{id}"的GET請求，用來獲取url中id值的User資訊
        // url中的id可通過@PathVariable繫結到函式的引數中
        return users.get(id);
    }

    @ApiOperation(value="更新使用者詳細資訊", notes="根據url的id來指定更新物件，並根據傳過來的user資訊來更新使用者詳細資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "String"),
            @ApiImplicitParam(name = "user", value = "使用者詳細實體user", required = true, dataType = "User")
    })
    @PutMapping(value="/{id}")
    public String putUser(@PathVariable String id, @ModelAttribute User user) {
        // 處理"/users/{id}"的PUT請求，用來更新User資訊
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @ApiOperation(value="刪除使用者", notes="根據url的id來指定刪除物件")
    @ApiImplicitParam(name = "id", value = "使用者ID", required = true, dataType = "String")
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable String id) {
        // 處理"/users/{id}"的DELETE請求，用來刪除User
        users.remove(id);
        return "success";
    }
}

4. 執行結果

瀏覽器訪問http://localhost:8080/swagger-ui.html，可得到如下介面

5. 原始碼下載

原始碼下載地址：https://download.csdn.net/download/huangjun0210/10813532