溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
前言
本文主要給大家介紹了關于Spring MVC用Swagger2構建動態RESTful API的相關內容，當多終端（WEB/移動端）需要公用業務邏輯時，一般會構建 RESTful 風格的服務提供給多終端使用。
為了減少與對應終端開發團隊頻繁溝通成本，剛開始我們會創建一份 RESTful API 文檔來記錄所有接口細節。
但隨著項目推進，這樣做所暴露出來的問題也越來越嚴重。
a. 接口眾多，細節復雜（需考慮不同的 HTTP 請求類型、HTTP 頭部信息、HTTP 請求內容..），高質量地創建這份文檔本身就是件非常吃力的事。
b. 不斷修改接口實現必須同步修改接口文檔，而文檔與代碼又處于兩個不同的媒介，除非有嚴格的管理機制，不然很容易導致不一致現象。
基于此，項目組在早些時間引入了 Swagger，經過幾個項目的沉淀，確實起到了很不錯的效果。
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
服務的方法、參數、模型緊密集成到服務器端的代碼，讓維護文檔和調整代碼融為一體，使 API 始終保持同步。
本文主要描述 Swagger 與 SpringMVC 的集成過程以及遇到的一些問題，權當拋磚引玉只用，具體項目具體分析。
1. Maven 依賴和最簡配置
<!--restfull APi swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
Spring-Context Swagger 配置：
<!-- swagger2 配置類--> <bean id="config" class="com.rambo.spm.core.config.SwaggerConfig"/> <!-- swagger2 靜態資源交由 spring 管理映射(springfox-swagger-ui.jar 為靜態資源包)--> <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:resources /> 由 Spring MVC 處理靜態資源，并添加一些有用的附加值功能。
a. <mvc:resources /> 允許靜態資源放在任何地方，如 WEB-INF 目錄下、類路徑下等，完全打破了靜態資源只能放在 Web 容器的根路徑下這個限制。
b. <mvc:resources /> 依據當前著名的 Page Speed、YSlow 等瀏覽器優化原則對靜態資源提供優化。
SwaggerConfig 配置類：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title("SPM Doc");
apiInfoBuilder.description("SPM Api文檔");
apiInfoBuilder.contact(new Contact("orson", "https://www.cnblogs.com/", ""));
apiInfoBuilder.version("2.0");
return apiInfoBuilder.build();
}
}
對于生成哪些請求方法 API ？ Swagger 提供了 RequestHandlerSelectors 對象的以下方法進行限制范圍：
2. 服務注解配置實踐
經過上述的操作，其實 Swagger 已經集成完畢，在項目開發推進中，只需在對應 RESTful 服務上添加對應注解即可。
@Api：注解在類上，說明該類的作用。可以標記一個 Controller 類做為 swagger 文檔資源，使用方式：
@Api(description = "用戶管理")
@ApiOperation：注解在方法上，說明方法的作用，每一個url資源的定義,使用方式：
@ApiOperation(value = "獲取所有用戶列表")
@ApiParam、@ApiImplicitParam：注解到參數上，說明該參數作用，使用方式：
@ApiParam(value = "用戶ID") String userId
上述都為最簡配置，構建清晰的 API 文檔已足夠，當然還有很豐富的注解，知道有就行了。
@RestController
@Api(description = "用戶管理")
public class UserRestController extends BaseController {
@Autowired
private SysUserService sysUserService;
@GetMapping("r/user/get")
@ApiOperation(value = "獲取特定用戶詳情")
public Object getUser(ModelMap modelMap, @ApiParam(value = "用戶ID") String userId) {
}
@PostMapping("r/user/add")
@ApiOperation(value = "添加用戶")
public Object addUser(ModelMap modelMap, @ModelAttribute @Valid SysUser user, BindingResult result) {
}
}
在項目后續使用中遇到的一些問題：
a. 一些方法入參如 HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 等等，這些參數在生成 API 文檔時是無意義的，Swagger 正確的配置方式？
剛開始時使用 @ApiParam(hidden = true) 注解這些參數，方法繁多的時候，這些類型的入參都要寫一遍，使用起來很冗余。
在 API 中發現 Docket 對象有 ignoredParameterTypes 方法，在配置類中統一定義忽略的參數類型即可，這樣就方便很多。
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.ignoredParameterTypes(ModelMap.class, HttpServletRequest.class,HttpServletResponse.class, BindingResult.class)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
b. 當請求的參數為封裝的對象時，怎樣進行注解？對象中的屬性怎樣注解？怎樣屏蔽對象中的莫個屬性？
請求的參數為對象時，使用Spring @ModelAttribute 注解對應對象，對象當中的屬性使用 @ApiModelProperty ，屏蔽莫個屬性 @ApiModelProperty(hidden = true)
@ApiModelProperty(hidden = true)
private String uuid;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("密碼")
private String passwd;
Swagger 有很豐富的工具，還能做很多事，本文所述只是能讓你迅速了解它、使用它、有需要多查資料、多翻博客。
總結
以上就是這篇文章的全部內容了，本文還有許多不足，希望本文的內容對大家的學習或者工作具有一定的參考學習價值，如果有疑問大家可以留言交流，謝謝大家對億速云的支持。
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
