SpringBoot指南|第四篇：集成swagger生成API文檔
本文介紹如何使用swagger生成API文檔。
為什么需要API的文檔
隨著互聯(lián)網(wǎng)技術(shù)的發(fā)展，現(xiàn)在的網(wǎng)站架構(gòu)基本都由原來的后端渲染，變成了：前端渲染、前后端分離的形態(tài)，而且前端技術(shù)和后端技術(shù)在各自的道路上越走越遠。前端和后端的唯一聯(lián)系，變成了API接口；API文檔變成了前后端開發(fā)人員聯(lián)系的紐帶，變得越來越重要，swagger就是一款讓你更好的書寫API文檔的框架。
目錄
- 1.依賴jar包
- 2.swagger 的自動注入配置
- 3.swagger-ui API文檔生成使用
- 4.結(jié)語
使用指南
1.依賴jar包
<!-- API Swagger begin -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>net.minidev</groupId>
<artifactId>json-smart</artifactId>
<version>2.3</version>
</dependency>
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20171018</version>
</dependency>
<!-- API Swagger end -->
2.swagger 的自動注入配置
源碼
/**
* com.xxx.web.config.SwaggerConfig.java
* Copyright 2018 Lifangyu, Inc. All rights reserved.
*/
package com.xxx.configs;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Desc:swagger api 的配置
* <p>
* 訪問:http://ip:port/swagger-ui.html
* [localhsot:8081/swagger-ui.html 可能有登錄攔截,需要先登錄系統(tǒng)后在訪問該地址]
* </p>
* <p>
* Created by lifangyu on 2018/3/19.
*/
@Conditional(SwaggerCondition.class)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* /api.* [訪問的路徑匹配,如:SwaggerApiController.java @RequestMapping("/api/v1") 符合該路徑匹配]
*
* @return
*/
@Bean
public Docket userApi() {
// 添加多個header或參數(shù)
/*ParameterBuilder parameterBuilder1 = new ParameterBuilder();
parameterBuilder1.name("clientCode").description("訪問的系統(tǒng)clientCode").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
ParameterBuilder parameterBuilder2 = new ParameterBuilder();
parameterBuilder2.name("timestamp").description("請求api的當前時間(long[yyyy-MM-dd HH:hh:ss SSS])").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
ParameterBuilder parameterBuilder3 = new ParameterBuilder();
parameterBuilder3.name("encrypt-key").description("請求api的認證密文").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
List<Parameter> parameterList = new ArrayList<Parameter>();
parameterList.add(parameterBuilder1.build());
parameterList.add(parameterBuilder2.build());
parameterList.add(parameterBuilder3.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false).globalOperationParameters(parameterList)
.select()
.paths(PathSelectors.regex("/api.*"))
.build();*/
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 選擇那些路徑和api會生成document
.apis(RequestHandlerSelectors.any()) // 對所有@Api注解進行監(jiān)控
// .paths(PathSelectors.any()) // 對所有路徑進行監(jiān)控[指定匹配路徑監(jiān)控(PathSelectors.regex("/api.*"))]
.build();
}
/**
* 確保以下配置的信息可用，否則不能訪問
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("****-**系統(tǒng)接口文檔")
.description("**-server系統(tǒng)接口文檔")
.license("Apache license")
.version("2.0")
.build();
}
}
為了防止在生產(chǎn)環(huán)境惡意攻擊api接口，建議關(guān)閉生產(chǎn)環(huán)境通過swagger api對接口的訪問，源碼：
/**
* com.xxx.web.config.SwaggerCondition.java
* Copyright 2018 Lifangyu, Inc. All rights reserved.
*/
package com.xxx.configs;
import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;
/**
* Desc:指定swagger api 生成的條件:非生產(chǎn)環(huán)境生成
* <p>
* Created by lifangyu on 2018/3/19.
*/
public class SwaggerCondition implements Condition {
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
return !"prod".equals(context.getEnvironment().getProperty("spring.profiles.active"));
}
}
3.swagger-ui API文檔生成使用
3.1:在寫好的 api controller 上添加注解 @Api(value = "demo controller", protocols = "json")
說明:指定該controller使用swagger生成api文檔;
3.2:在方法上添加注解
@ApiOperation(value = "系統(tǒng)-方法", httpMethod = "POST", notes = "接口簡介")
說明：該方法使用swagger 生成api接口文檔，提供測試服務;
demo
@RestController
@Slf4j
@Api
@RequestMapping("/xxx/api/v1")
public class GpsApi {
...
@PostMapping("syncGpsInfo")
@ApiOperation(value = "測試系統(tǒng)-gps信息同步", httpMethod = "POST", notes = "gps信息同步")
@RequestLogger("測試系統(tǒng)-gps信息同步[/as/api/v1/syncGpsInfo]")
@ResponseBody
public ResponseVo syncGspInfo(@RequestBody RequestVo<GpsSyncRequestVo> requestVo) {
......
}
...
}
swagger-ui api文檔 的訪問
啟動應用，在瀏覽器輸入：http://ip:port/swagger-ui.html
類似下圖：
swagger.png
可以提供接口api文檔的說明和api的測試！
附：swagger 生成API文檔的注釋
@Api：用在類上，說明該類的作用。
@ApiOperation：注解來給API增加方法說明。
@ApiImplicitParams : 用在方法上包含一組參數(shù)說明。
@ApiImplicitParam：用來注解來給方法入?yún)⒃黾诱f明。
@ApiResponses：用于表示一組響應
@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息
1.code：數(shù)字，例如400
2.message：信息，例如"請求參數(shù)沒填好"
3.response：拋出異常的類
@ApiModel：描述一個Model的信息（一般用在請求參數(shù)無法使用@ApiImplicitParam注解進行描述的時候）
@ApiModelProperty：描述一個model的屬性
注意：@ApiImplicitParam的參數(shù)說明：
1.paramType：指定參數(shù)放在哪個地方
2.header：請求參數(shù)放置于Request Header，使用@RequestHeader獲取
3.query：請求參數(shù)放置于請求地址，使用@RequestParam獲取
4.path：（用于restful接口）-->請求參數(shù)的獲?。篅PathVariable
5.body：（不常用）
6.form（不常用）
7.name：參數(shù)名
8.dataType：參數(shù)類型
9.required：參數(shù)是否必須傳 true | false
10.value：說明參數(shù)的意思
11.defaultValue：參數(shù)的默認值
結(jié)語
到此本文就結(jié)束了，關(guān)注公眾號查看更多推送！！！
關(guān)注我的公眾號
