碼上快樂

相關內容    簡體    繁體

集成Swagger在線調試

本文轉載自   查看原文   2019-04-16 10:00   770    spring boot

SpringBoot 是為了簡化 Spring 應用的創建、運行、調試、部署等一系列問題而誕生的產物，自動裝配的特性讓我們可以更好的關注業務本身而不是外部的XML配置，我們只需遵循規范，引入相關的依賴就可以輕易的搭建出一個 WEB 工程

隨着互聯網技術的發展，現在的網站架構基本都由原來的后端渲染，變成了：前端渲染、前后端分離的形態，而且前端技術和后端技術在各自的道路上越走越遠。

前端和后端唯一聯系，變成了API接口；API文檔自然就成了前后端開發人員聯系的紐帶，變得尤為的重要，swagger就是一款讓你更好的書寫API文檔的框架。

文檔工具

沒有API文檔工具之前，基本都是手寫API文檔的，如有在Word上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好壞。但是這種手寫文檔帶來的弊端就是維護起來苦不堪言，對於接口容易發生變化的開發者來說，維護文檔就是噩夢….

好在現如今市場上書寫API文檔的工具有很多，常見的有 postman、yapi、阿里的RAP 但是能稱之為框架的，估計也只有swagger了。

swagger 優缺點

  • 集成方便，功能強大
  • 在線調試與文檔生成
  • 代碼耦合，需要注解支持，但不影響程序性能

導入依賴

在 pom.xml 中添加 swagger-spring-boot-starter 的依賴

1
2
3
4
5
6
7
8
9
 
<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
 <groupId>com.battcn</groupId>
 <artifactId>swagger-spring-boot-starter</artifactId>
 <version>1.4.5-RELEASE</version>
</dependency>

屬性配置

配置spring.swagger.enabled開啟swagger的使用，如果在生產環境中不想用可以在對應的profile下面將它設置為spring.swagger.enabled=false，這樣一來接口就不存在暴露的風險

1
2
3
4
 
# 掃描的包路徑,默認掃描所有
spring.swagger.base-package=com.battcn
# 默認為 true
spring.swagger.enabled=true

更多屬性更多屬性

實體類

swagger 提供了非常齊全的注解，為POJO提供了@ApiModel、@ApiModelProperty，以便更好的渲染最終結果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
package com.battcn.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**
 * @author Levin
 * @since 2018/5/10 0007
 */
@ApiModel
public class User implements Serializable {

 private static final long serialVersionUID = 8655851615465363473L;

 private Long id;
 @ApiModelProperty("用戶名")
 private String username;
 @ApiModelProperty("密碼")
 private String password;

 // TODO 省略get set
}

restful 風格接口

注解描述

  • @Api： 描述Controller
  • @ApiIgnore： 忽略該Controller，指不對當前類做掃描
  • @ApiOperation： 描述Controller類中的method接口
  • @ApiParam： 單個參數描述，與@ApiImplicitParam不同的是，他是寫在參數左側的。如（@ApiParam(name = "username",value = "用戶名") String username）
  • @ApiModel： 描述POJO對象
  • @ApiProperty： 描述POJO對象中的屬性值
  • @ApiImplicitParam： 描述單個入參信息
  • @ApiImplicitParams： 描述多個入參信息
  • @ApiResponse： 描述單個出參信息
  • @ApiResponses： 描述多個出參信息
  • @ApiError： 接口錯誤所返回的信息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
package com.battcn.controller;

import com.battcn.entity.User;
import com.battcn.swagger.properties.ApiDataType;
import com.battcn.swagger.properties.ApiParamType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

/**
 * swagger
 *
 * @author Levin
 * @since 2018/5/16 0016
 */
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用戶管理", value = "用戶管理")
public class UserController {

 private static final Logger log = LoggerFactory.getLogger(UserController.class);

 @GetMapping
 @ApiOperation(value = "條件查詢（DONE）")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "username", value = "用戶名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
 @ApiImplicitParam(name = "password", value = "密碼", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
 })
 public User query(String username, String password) {
 log.info("多個參數用 @ApiImplicitParams");
 return new User(1L, username, password);
 }

 @GetMapping("/{id}")
 @ApiOperation(value = "主鍵查詢（DONE）")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "id", value = "用戶編號", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
 })
 public User get(@PathVariable Long id) {
 log.info("單個參數用 @ApiImplicitParam");
 return new User(id, "u1", "p1");
 }

 @DeleteMapping("/{id}")
 @ApiOperation(value = "刪除用戶（DONE）")
 @ApiImplicitParam(name = "id", value = "用戶編號", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
 public void delete(@PathVariable Long id) {
 log.info("單個參數用 ApiImplicitParam");
 }

 @PostMapping
 @ApiOperation(value = "添加用戶（DONE）")
 public User post(@RequestBody User user) {
 log.info("如果是 POST PUT 這種帶 @RequestBody 的可以不用寫 @ApiImplicitParam");
 return user;
 }

 @PutMapping("/{id}")
 @ApiOperation(value = "修改用戶（DONE）")
 public void put(@PathVariable Long id, @RequestBody User user) {
 log.info("如果你不想寫 @ApiImplicitParam 那么 swagger 也會使用默認的參數名作為描述信息 ");
 }
}

主函數

添加 @EnableSwagger2Doc 即可

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
package com.battcn;

import com.battcn.swagger.annotation.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author Levin
 */
@EnableSwagger2Doc
@SpringBootApplication
public class Chapter10Application {

 public static void main(String[] args) {
 SpringApplication.run(Chapter10Application.class, args);
 }
}

測試

由於上面的接口是 restful 風格的接口，添加和修改無法通過瀏覽器完成，以前都是自己編寫junit或者使用postman之類的工具。現在只需要打開瀏覽器輸入 http://localhost:8080/swagger-ui.html，更多操作請自行體驗…

渲染效果渲染效果


免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。



猜您在找 Spring Boot 2.X(十五)：集成 Swagger2 開發 API 文檔（在線+離線） springMVC集成swagger2 springboot快速集成swagger SpringBoot集成Swagger3 WebApi 集成 Swagger javaweb集成swagger SpringBoot 集成Swagger swagger部署和dubbo集成(二)restful swagger接入 KEIL在線調試 groovy在線調試
 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM