SpringBoot整合Swagger2 – 小科科的春天

Our-task介紹

本篇博客是我github上our-task：一個完整的清單管理系統的配套教程文檔，這是SpringBoot+Vue開發的前後端分離清單管理工具，仿滴答清單。目前已部署在阿里雲ECS上，可進行在線預覽，隨意使用（附詳細教程），大家感興趣的話，歡迎給個star!

阿里雲預覽地址

整合步驟

maven依賴

<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>
    <!--Swagger-UI API文檔生產工具-->
    <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>
</dependencies>

User實體

新建User類，方便後續驗證配置是否正確，其中

@ApiModelProperty用於方法，字段；表示對model屬性的說明或者數據操作更改。

public class User{

    @ApiModelProperty(value = "用戶id")
    Integer id;

    @ApiModelProperty(value = "用戶姓名")
    String username;

    @ApiModelProperty(value = "用戶密碼")
    String password;

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

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

Swagger-UI配置類

大家只需要修改其中的basePackage("com.example.demo.controller")，把這個改為自己的controller層的包名就可以了，Swagger-UI就會掃描該包下所有的Controller，從而顯示在前段界面上。

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為當前包下controller生成API文檔
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("配置SwaggerUI")
                .description("Swagger-UI-Demo")
                .version("1.0")
                .build();
    }
}

UserController

@RestController
@Api(value = "用戶控制器", tags = {"用戶操作"})
public class UserController {
    @GetMapping("/hello")
    @ApiOperation("打招呼")
    public String hello(){
        return "你好，我是小娜";
    }

    @PostMapping("/login")
    @ApiOperation("登錄")
    public String login(@RequestBody @ApiParam("用戶對象") User user){
        return "你好" + user.toString();
    }
}

註解含義說明

@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：描述一個請求參數，可以配置參數的中文含義，還可以給參數設置默認值
@ApiImplicitParams：描述由多個 @ApiImplicitParam 註解的參數組成的請求參數列表

配套代碼

寫了這麼多，還是擔心大家出現問題解決不了，所以我把配套Demo放在github上了，大家有問題可以的話可以去下載運行看看。

Swagger-UI-Demo