Swagger2邊寫代碼邊寫文檔

​

 

做爲一個開發人員最怕的就是寫文檔了，可是要想成爲一個合格的程序員，寫好文檔也是一個必備的技能。開發中咱們常常要寫接口服務，既然是服務就要跟別人對接，那不免要寫接口文檔，那麼如何」優雅「的寫接口文檔呢？本文介紹一個在寫代碼的過程就能夠寫完接口文檔的工具——Swagger2（江湖人稱絲襪哥😂）

 

下文基於 SpringBoot + Maven 介紹 Swagger2 的使用

加入依賴

​ <!--Swagger-ui配置--> <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>​

編寫Swagger全局配置

​package com.ziyou.test.admin.config;​import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Parameter;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;​import java.util.ArrayList;import java.util.List;​/** * <br> * <b>功能：</b><br> * <b>做者：</b>@author 子悠<br> * <b>日期：</b>2019-03-28 23:35<br> * <b>詳細說明：</b>Swagger配置類， * UI地址： http://127.0.0.1:8084/swagger-ui.html * JSON文檔地址 http://127.0.0.1:8084/v2/api-docs * <br> */@EnableSwagger2@Configurationpublic class Swagger2Config {​ @Bean public Docket createRestApi() { //header中增長 token_id參數，沒有能夠去掉 ParameterBuilder token = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); token.name("token_id").description("user token") .modelRef(new ModelRef("string")).parameterType("header") .required(false).build(); pars.add(token.build()); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // 指定controller存放的目錄路徑 .apis(RequestHandlerSelectors.basePackage("com.ziyou.test.admin.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars); }​ private ApiInfo apiInfo() { return new ApiInfoBuilder() // 文檔標題 .title("這裏是文檔標題") // 文檔描述 .description("這裏是文檔描述") .termsOfServiceUrl("這裏能夠增長需求文檔 wiki 地址") .version("v1")//定義版本號 .build(); }​}​

Controller 編寫

•類上面增長@Api註解

​@Api(value = "後臺管理", tags = "Administrator - 後臺主入口")public class MainController {}​

•方法上增長@ApiOperation註解

​ @ApiOperation(value = "用戶登陸——可用", httpMethod = "POST", response = ResultMsg.class) public ResultMsg login(@RequestBody LoginBean loginBean) throws Exception {}//value: 表示描述//httpMethod: 支持的請求方式// response: 返回的自定義的實體類​

•方法參數 Model 屬性自定義設置

package com.ziyou.test.admin.bean;​import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;​import java.util.Date;​@ApiModel(value = "用戶對象", description = "用戶對象model")public class LoginBean {​ @ApiModelProperty(value = "用戶登陸帳戶", name = "loginName", required = true, example = "admin") private String loginName;// 帳號 @ApiModelProperty(value = "用戶登陸密碼", name = "loginPwd", required = true, example = "123456") private String loginPwd;// 密碼 @ApiModelProperty(hidden = true) private String salt;// 鹽值​ public String getLoginName() { return this.loginName; } public void setLoginName(String loginName) { this.loginName=loginName; } public String getLoginPwd() { return this.loginPwd; } public void setLoginPwd(String loginPwd) { this.loginPwd=loginPwd; } public String getSalt() { return this.salt; } public void setSalt(String salt) { this.salt=salt; }}​

@ApiModel註解用在 model 類上 @ApiModelProperty 用於 model 的屬性上

•能夠定義是否 required, example, hidden, value, name等參數•hidden 爲 true 在頁面上就不會顯示在字段

界面使用

•

啓動項目，打開項目文檔地址：http://ip:port/swagger-ui.html^[1

•

如圖顯示的內容。還能夠添加 header 參數，以及在網頁上進行測試

 

增長密碼

•接口文檔咱們每每須要讓有權限的人查看，因此咱們能夠根據 Spring-Security增長帳號密碼管理。•增長依賴

​<!--Swagger-ui 密碼配置配置--><dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId></dependency>​

•配置文件中增長帳號密碼配置

​Spring: security: basic: path: /swagger-ui.html enabled: true user: name: admin password: 123456​# swagger-ui.html帳號密碼配置信息，根據版本不一樣，可能須要以下方式#security.basic.path=/swagger-ui.html#security.basic.enabled=true#security.user.name=admin#security.user.password=123456​

•增長了依賴和帳號密碼後重啓項目，再次打開文檔地址就要去輸入帳號和密碼輸入對應的帳號和密碼就能夠登陸了。

小坑

•若是在啓動的時候出現以下錯誤，是由於新版的 Swagger2須要高版本的 guava

​***************************APPLICATION FAILED TO START***************************​Description:​An attempt was made to call the method com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable; but it does not exist. Its class, com.google.common.collect.FluentIterable, is available from the following locations:​ jar:file:/Users/silence/Work/maven-repo3/com/google/guava/guava/19.0/guava-19.0.jar!/com/google/common/collect/FluentIterable.class​It was loaded from the following location:​ file:/Users/silence/Work/maven-repo3/com/google/guava/guava/19.0/guava-19.0.jar​Action:​Correct the classpath of your application so that it contains a single, compatible version of com.google.common.collect.FluentIterable​

•解決方案增長以下配置便可

​<dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>20.0</version></dependency>​

•

Security 過濾特定路徑

•針對非文檔路徑的其餘路徑，咱們須要進行過濾，採用以下方式。

/** * 取消 security 對接口的攔截，只在 swaggerui 進行攔截 * * @param web * @throws Exception */@Overridepublic void configure(WebSecurity web) throws Exception { super.configure(web); //這裏填寫須要過濾的路徑 web.ignoring().antMatchers("/api/v1/admin/**");}

}

小結

Swagger2 讓開發人員在編寫代碼的時候就完成了接口文檔，方便快捷。並且隨項目一塊兒部署，不用擔憂丟失，須要的時候只要打開項目地址就能夠了，十分方便。

在使用 Swagger2寫完接口文檔後，還能夠直接導出 JSON 文件，訪問路徑`http://ip:port/v2/api-docs`能夠看到JSON 文檔。生成的 JSON 文檔能夠配合 YAPI 或者 POSTMAN 使用都是能夠的。

 

---

精彩回顧：

面試點：Java 中 hashCode() 和 equals() 的關係

容器鏈接[Docker 系列-7]

現現在的技術浪潮中，咱們到底該作些什麼？

 

強烈推薦：

《Java 極客技術》知識星球限時優惠，如今加入只需 50 元，僅限前 1000 名，機不可失時再也不來。趁早行動吧！

https://t.zsxq.com/J6Em2nU

 

隆重介紹：

Java 極客技術公衆號，是由一羣熱愛 Java 開發的技術人組建成立，專一分享原創、高質量的 Java 文章。若是您以爲咱們的文章還不錯，請幫忙讚揚、在看、轉發支持，鼓勵咱們分享出更好的文章。