一 前言

這篇文章主要是帶大家入門下如何使用OpenAPI, 筆者在github上找到對應得swagger項目都沒找到javase得人門文章，看了下是基于JAX-RS，吐血了；

二 什么是 OpenAPI，

OpenAPI 是 一種基于Resful 風格 對 API進行格式化描述的一種規范； 允許你描述你整個項目的API，簡單的講就是一種接口文檔生成的規范；包括如下幾點 ：

端點描述（如 GET /user , Post /user）;

操作的參數，入輸入參數，輸出參數；

認證信息

聯系信息，許可條款，聲明等

OpenAPI 3.0 Specification

三 什么是 Swagger

Swagger 由多個組件組成，它是一個開源的構建工具，其作用就是以 OpenAPI 為 規范基準， 能夠幫助開發人員設計，構建文檔，測試接口，文檔規范化，和消費掉Restful API；說白了就是 OpenAPI 的實現，能夠生成接口文檔，以后不用自己手寫了！！！ 我們可以看下其主要組件如下：

Swagger Editor 是一個編輯工具，可以編輯描述API；

Swagger UI 能讓OpenAPI呈現出規范的可交互的API文檔，以供他人查閱；

Swagger Codegen 基于OpenAPI規范 能夠生成客戶端類庫，服務端文檔和存根，并且支持多語言，支持使用Docker,jar等方式運行構建；

更多組件詳細看官網：swagger doc，看了官網的ylm格式基本結構暈，一堆黑的，客戶體驗非常不友好吐槽一下！看了github是基于JAX-RS 應用 ，不是很懂，再吐槽一下；

四 API生成

4.1 相關注釋

4.2 pom.xml

<dependencies><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><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.5.22</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.22</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.16.18</version><optional>true</optional></dependency></dependencies>

4.3 swagger配置

主要是配置一些項目得基本信息，注解路徑，項目主要聯系人等；比較重要是@EnableSwagger2表示開啟Swagger；

/*** @Author lsc* <p> swagger 配置 </p>*/ @Configuration @EnableSwagger2 public class SwaggerConfig {@Beanpublic Docket createRestApi() {// 構建文檔Docket docket = new Docket(DocumentationType.SWAGGER_2);// 文檔信息Docket build = docket.apiInfo(apiInfo())// 查詢.select()// 注解包的路徑.apis(RequestHandlerSelectors.basePackage("com.zszxz.swagger.controller"))// 任何路徑.paths(PathSelectors.any()).build();return build;}/* ** @Author lsc* <p> 文檔信息</p>* @Param []* @Return springfox.documentation.service.ApiInfo*/private ApiInfo apiInfo() {// 文檔對象構建器ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();// 文檔標題ApiInfo apiInfo = apiInfoBuilder.title("知識追尋者（公眾號） API doc")// 描述信息.description("知識追尋者第一次操作OpenAPI！！！！！")// 版本號.version("v1")// 聯系人.contact(new Contact("知識追尋者", "https://blog.csdn.net/youku1327", "lsc50534314@gmail.com"))// 聲明許可.license("知識追尋者許可")// 許可路徑，這邊是我的github.licenseUrl("https://github.com/zszxz").build();return apiInfo;} }

4.4 實體

/*** @Author lsc* <p> </p>*/ @Data @ApiModel(description = "用戶知識追尋者實體") public class ZSZXZ {@ApiModelProperty(value = "姓名",dataType = "String")private String name;@ApiModelProperty(value = "郵件",dataType = "String")private String email;@ApiModelProperty(value = "愛好",dataType = "String")private String hobby; }

4.5 controller

/*** @Author lsc* <p> </p>*/ @RestController // 資源信息 @Api(value = "知識追尋者文檔API") public class SwaggerController {// 方法注釋@ApiOperation(value = "獲取用戶")// 響應信息@ApiResponse(code = 200,message = "獲取用戶列表成功")@GetMapping("zszxz")public ResponseEntity getUser(){ZSZXZ zszxz = new ZSZXZ();zszxz.setName("知識追尋者");zszxz.setHobby("愛睡覺");zszxz.setEmail("不告訴你");return ResponseEntity.ok(zszxz);}// 方法注釋@ApiOperation(value = "跟據用戶編號獲取用戶")// 響應信息@ApiResponses({@ApiResponse(code = 200,message = "獲取用戶列表成功"),@ApiResponse(code = 204,message = "沒有內容")})// 參數信息@ApiImplicitParam(name = "id", value = "用戶編號", dataType = "ZSZXZ",required = true, paramType = "path")@GetMapping("zszxz/{id}")public ResponseEntity getUserById(@PathVariable Long id){ZSZXZ zszxz = new ZSZXZ();zszxz.setName("知識追尋者");zszxz.setHobby("愛睡覺");zszxz.setEmail("不告訴你");return ResponseEntity.ok(zszxz);}@PostMapping("zszxz")// 響應信息@ApiResponse(code = 201,message = "添加用戶列表成功")// 方法信息@ApiOperation(value = "添加用戶")public ResponseEntity addUser(@RequestBody ZSZXZ zszxz){System.out.println("save the user:"+zszxz);return ResponseEntity.ok("success save the user");}// 響應信息@ApiResponse(code = 200,message = "修改用戶成功")@ApiOperation(value = "修改用戶",notes = "修改用戶")@PutMapping("zszxz/{id}")// 參數信息 多個參數使用注釋中得內容, @RequestBody 修斯參數沒必要寫/*@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path"),@ApiImplicitParam(name = "user", value = "用戶", dataType = "ZSZXZ",required = true, paramType = "json")})*/@ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path")public ResponseEntity updateUser(@PathVariable Long id ,@RequestBody ZSZXZ zszxz){System.out.println("update the user:"+zszxz);return ResponseEntity.ok("success update the user,the number is :"+id);}// 響應信息@ApiResponses({@ApiResponse(code = 200,message = "刪除用戶成功"),@ApiResponse(code = 401,message = "沒有權限")})@ApiOperation(value = "刪除用戶")@DeleteMapping("zszxz/{id}")@ApiImplicitParam(name = "id", value = "用戶編號", dataType = "Long",required = true,paramType = "path")public ResponseEntity updateUser(@PathVariable Long id ){System.out.println("delete the user :"+id);return ResponseEntity.ok("delete the user :"+id);}}

4.6 生成結果

默認路徑：localhost:8080/swagger-ui.html#/

4.7 查看實體

4.8 查詢接口測試

打開測試查詢接口：

測試結果：

4.9 添加用戶測試

由于注解時偷懶沒加example，所以這邊測試要自己動手寫測試數據；

測試結果如下

五 結語

修改和刪除就不測試了，很簡單，讀者自行測試；基本常用得注解使用都過了，其余得讀者自行研究，總體來說使用還是很愉快，默認文檔路徑是可以修改得，讀者自行搜索；源碼請看作者博客專欄說明；

總結

以上是生活随笔為你收集整理的没有required_springboot-使用OpenAPI之后我再也没有写过接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。