SpringBoot整合Swagger-ui

1. 引入依賴

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

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

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

1. 添加配置類

// 啟動時加載類
@Configuration
// 啟用Swagger API文檔
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("客戶管理")
                .description("客戶管理中心 API 1.0 操作文檔")
                //服務條款網址
                .termsOfServiceUrl("https://www.cnblogs.com/wadmwz/")
                .version("1.0")
                .contact(new Contact("王智家園", "https://www.cnblogs.com/wadmwz/", "[email protected]"))
                .build();
    }

}
 

1. Swagger常用註解

@Api的使用

API作用在Controller,作為swagger文檔資源,該註解將一個controller標註為一個Swagger資源(API). 在默認情況下，Swagger-Core 只會掃描解析具有 @Api 註解的類，而會自動忽略其他類別資源（JAX-RS endpoints、Servlets 等）的註解。

@Api(value = "消息",description = "消息操作 API", position = 100, protocols = "http")
@RestController
@RequestMapping("message")
public class MessageController {
}

啟動項目,訪問http://localhost:8080/swagger-ui.html#/message-controller 就可以看到效果,自動將MessageController內的方法都添加映射,並標明了每種方法的請求方式

@ApiOperation 的使用

ApiOperation 定義在方法上，描述方法名、方法解釋、返回信息、標記等信息。

@ApiOperation(
        value = "消息列表",
        notes = "完整的消息內容列表",
        produces = "application/json, application/xml",
        consumes = "application/json, application/xml",
        response = List.class
)
@GetMapping(value = "messages")
public List<Message> list() {
    List<Message> messages = this.messageRepository.findAll();
    return messages;
}

@ApiImplicitParams 和 @ApiImplicitParam 的使用

@ApiImplicitParams 用於描述方法的返回信息，和 @ApiImplicitParam 註解配合使用；@ApiImplicitParam 用來描述具體某一個參數的信息，包括參數的名稱、類型、限制等信息。

@ApiOperation(
        value = "添加信息",
        notes = "根據傳遞的參數創建信息"
)
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "消息ID", required = true, dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "text", value = "消息正文", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "summary", value = "摘要", required = false, dataType = "String", paramType = "query"),

})
@PostMapping(value = "message")
public Message create(Message message) {
    message = this.messageRepository.save(message);
    return message;
}

@ApiResponses 和 @ApiResponse 的使用

@ApiResponses 主要封裝方法的返回信息和 @ApiResponse 配置起來使用，@ApiResponse 定義返回的具體信息包括返回碼、返回信息等。

@ApiOperation(value = "修改信息", notes = "根據參數修改信息")
@ApiResponses({
        @ApiResponse(code = 100, message = "請求信息有誤"),
        @ApiResponse(code = 101, message = "未授權"),
        @ApiResponse(code = 103, message = "禁止訪問"),
        @ApiResponse(code = 104, message = "請求路徑不存在"),
        @ApiResponse(code = 200, message = "服務器內部錯誤"),
})
@PutMapping(value = "message")
public Message modify(Message message) {
    Message messageResult=this.messageRepository.update(message);
    return messageResult;
}

@ApiModel 和 @ApiModelProperty 的使用

在實際的項目中我們常常會封裝一個對象作為返回值，@ApiModel 就是負責描述對象的信息，@ApiModelProperty 負責描述對象中屬性的相關內容。

@ApiModel(description = "響應對象")
public class BaseResult<T> {

    private static final int SUCCESS_CODE = 0;
    private static final String SUCCESS_MESSAGE = "成功";

    @ApiModelProperty(value = "響應碼", name = "code", required = true, example = "" + SUCCESS_CODE)
    private int code;

    @ApiModelProperty(value = "響應消息", name = "msg", required = true, example = SUCCESS_MESSAGE)
    private String msg;

    @ApiModelProperty(value = "響應數據", name = "data")
    private T data;

    private BaseResult(int code, String msg, T data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    private BaseResult() {
        this(SUCCESS_CODE, SUCCESS_MESSAGE);
    }

    private BaseResult(int code, String msg) {
        this(code, msg, null);
    }

    private BaseResult(T data) {
        this(SUCCESS_CODE, SUCCESS_MESSAGE, data);
    }

    public static <T> BaseResult<T> success() {
        return new BaseResult<>();
    }

    public static <T> BaseResult<T> successWithData(T data) {
        return new BaseResult<>(data);
    }

    public static <T> BaseResult<T> failWithCodeAndMsg(int code, String msg) {
        return new BaseResult<>(code, msg, null);
    }

    public static <T> BaseResult<T> buildWithParam(ResponseParam param) {
        return new BaseResult<>(param.getCode(), param.getMsg(), null);
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }



    public static class ResponseParam {
        private int code;
        private String msg;

        private ResponseParam(int code, String msg) {
            this.code = code;
            this.msg = msg;
        }

        public static ResponseParam buildParam(int code, String msg) {
            return new ResponseParam(code, msg);
        }

        public int getCode() {
            return code;
        }

        public void setCode(int code) {
            this.code = code;
        }

        public String getMsg() {
            return msg;
        }

        public void setMsg(String msg) {
            this.msg = msg;
        }
    }

}

@PatchMapping(value="/message/text")
public BaseResult<Message> patch(Message message) {
    Message messageResult=this.messageRepository.updateText(message);
    return BaseResult.successWithData(messageResult);
}

源碼請查看 : https://github.com/MissWangLove/SpringBoot

SpringBoot整合Swagger-ui