<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>
// 啓動時加載類 @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/", "15713598138@sina.cn")) .build(); } }
做用範圍 | API | 使用位置 |
---|---|---|
協議集描述 | @Api | 用於 Controller 類上 |
協議描述 | @ApiOperation | 用在 Controller 的方法上 |
非對象參數集 | @ApiImplicitParams | 用在 Controller 的方法上 |
非對象參數描述 | @ApiImplicitParam | 用在 @ApiImplicitParams 的方法裏邊 |
響應集 | @ApiResponses | 用在 Controller 的方法上 |
響應信息參數 | @ApiResponse | 用在 @ApiResponses 裏邊 |
描述返回對象的意義 | @ApiModel | 用在返回對象類上 |
對象屬性 | @ApiModelProperty | 用在出入參數對象的字段上 |
API做用在Controller,做爲swagger文檔資源,該註解將一個controller標註爲一個Swagger資源(API). 在默認狀況下,Swagger-Core 只會掃描解析具備 @Api 註解的類,而會自動忽略其餘類別資源(JAX-RS endpoints、Servlets 等)的註解。html
@Api(value = "消息",description = "消息操做 API", position = 100, protocols = "http") @RestController @RequestMapping("message") public class MessageController { }
啓動項目,訪問http://localhost:8080/swagger-ui.html#/message-controller 就能夠看到效果,自動將MessageController內的方法都添加映射,並標明瞭每種方法的請求方式git
ApiOperation 定義在方法上,描述方法名、方法解釋、返回信息、標記等信息。github
@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; }
屬性名稱 | 備註 |
---|---|
value | url 的路徑值 |
tags | 若是設置這個值,value 的值會被覆蓋 |
description | 對 API 資源的描述 |
produces | For example, "application/json, application/xml" |
consumes | For example, "application/json, application/xml" |
protocols | Possible values: http, https, ws, wss |
authorizations | 高級特性認證時配置 |
hidden | 配置爲 true 將在文檔中隱藏 |
response | 返回的對象 |
responseContainer | 這些對象是有效的 "List", "Set" or "Map",其餘無效 |
httpMethod | "GET"、"HEAD"、"POST"、"PUT"、"DELETE"、"OPTIONS" and "PATCH" |
code | http 的狀態碼 默認 200 |
extensions | 擴展屬性 |
@ApiImplicitParams 用於描述方法的返回信息,和 @ApiImplicitParam 註解配合使用;@ApiImplicitParam 用來描述具體某一個參數的信息,包括參數的名稱、類型、限制等信息。web
@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; }
屬性名稱 | 備註 |
---|---|
name | 接收參數名 |
value | 接收參數的意義描述 |
required | 參數是否必填值爲 true 或者 false |
dataType | 參數的數據類型只做爲標誌說明,並無實際驗證 |
paramType | 查詢參數類型,其值: path 以地址的形式提交數據 query 直接跟參數完成自動映射賦 body 以流的形式提交,僅支持 POST header 參數在 request headers 裏邊提交 form 以 form 表單的形式提交 僅支持 POST |
@ApiResponses 主要封裝方法的返回信息和 @ApiResponse 配置起來使用,@ApiResponse 定義返回的具體信息包括返回碼、返回信息等。spring
@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; }
屬性名稱 | 備註 |
---|---|
code | http 的狀態碼 |
message | 描述 |
response | 默認響應類 Void |
reference | 參考 |
responseHeaders | 封裝返回信息 |
responseContainer | 字符串 |
在實際的項目中咱們經常會封裝一個對象做爲返回值,@ApiModel 就是負責描述對象的信息,@ApiModelProperty 負責描述對象中屬性的相關內容。json
@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); }
屬性名稱 | 備註 |
---|---|
value | 屬性描述 |
name | 若是配置覆蓋屬性名稱 |
allowableValues | 容許的值 |
access | 能夠不配置 |
notes | 沒有使用 |
dataType | 數據類型 |
required | 是否爲必傳參數 |
position | 顯示的順序位置 |
hidden | 是否所以 |
example | 舉例 |
readOnly | 只讀 |
reference | 引用 |
源碼請查看 : https://github.com/MissWangLove/SpringBootapi