21-SpringBoot之Swagger——整合Swagger2

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