團隊開發痛點：
-
API 介面眾多，細節復雜，需要考慮不同的HTTP請求型別、HTTP頭部資訊、HTTP請求內容等，想要高質量的完成這份檔案需要耗費大量的精力；
-
難以維護，隨著需求的變更和專案的優化、推進，介面的細節在不斷地演變，介面描述檔案也需要同步修訂，可是檔案和代碼處于兩個不同的媒介，除非有嚴格的管理機制，否則很容易出現檔案、介面不一致的情況
Swagger2 的出現就是為了從根本上解決上述問題，它作為一個規范和完整的框架，可以用于生成、描述、呼叫和可視化 RESTful 風格的 Web 服務：
-
介面檔案在線自動生成，檔案隨介面變動實時更新，節省維護成本
-
支持在線介面測驗，不依賴第三方工具
注意點：Swagger2是支持在線介面測驗的，所以對于生產環境，準生產環境，必須屏蔽該入口，防止因為Swagger2的在線介面測驗導致生產問題或者資料污染，
第一步集成pom
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
第二步：Swagger2 的配置
package com.common.base.config;
import com.common.base.utils.StringUtil;
import com.common.base.utils.YamlUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Auther: tony_t_peng
* @Date: 2020-08-14 15:42
* @Description:
*/
@Configuration
//是否開啟swagger，正式環境一般是需要關閉的（避免不必要的漏洞暴露！），可根據springboot的多環境配置進行設定
@ConditionalOnProperty(name = "swagger.enable", havingValue = "https://www.cnblogs.com/ptcnblog/p/true")
@EnableSwagger2
public class Swagger2Config {
@Autowired
private ProfileConfig profileConfig;
private static final String SWAGGER_BASE_PACKAGE="swagger.base.package";
// swagger2的組態檔，這里可以配置swagger2的一些基本的內容，比如掃描的包等等
@Bean
public Docket createRestApi() {
String active = profileConfig.getActiveProfile();//讀取當前的環境active
String swaggerBasePackage = YamlUtil.getApplicationVal(SWAGGER_BASE_PACKAGE,active);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 為當前包路徑
.apis(RequestHandlerSelectors.basePackage(swaggerBasePackage)).paths(PathSelectors.any())
.build();
}
// 構建 api檔案的詳細資訊函式,注意這里的注解參考的是哪個
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 頁面標題
.title("Swagger2 構建RESTful API")
// 創建人資訊
.contact(new Contact("TONY_T_PENG", "", ""))
// 版本號
.version("1.0")
// 描述
.description("API 描述")
.build();
}
}
/**
* @Auther: tony_t_peng
* @Date: 2020-08-07 15:35
* @Description: 獲取profile.active提供方法，此方法可以在sping容器完成創建之前，
* 獲取環境引數
*/
@Configuration
@AutoConfigureOrder(0)
public class ProfileConfig {
@Autowired
private ApplicationContext context;
public String getActiveProfile() {
return context.getEnvironment().getActiveProfiles()[0];
}
}
這兩步可以集成到公共服務中，子專案pom去依賴公共服務，減少重復造輪子，
第三步： 配置api
@RestController
@RequestMapping("/question")
@Api("questionController相關的api")
public class QuestionController {
public static Logger logger = LoggerFactory.getLogger(QuestionController.class);
@Autowired
private UwConvertQuestionService convertQuestionService;
@RequestMapping(value = "https://www.cnblogs.com/test",method = RequestMethod.POST)
@ApiOperation(value = "https://www.cnblogs.com/ptcnblog/p/測驗",tags={"測驗標題"}, notes = "標題內容",httpMethod = "POST")
public Result<ConvertQuestionResponseMO> test(@RequestBody @Valid ConvertQuestionRequestMO request)
{
return null;
}
}
注：如果想要屏蔽某些介面：使用注解@ApiIgnore
第四步：配置掃包路徑和swagger啟動開關，swagger功能開啟
服務配置掃包路徑：application-dev.yml
swagger:
enable: true
base:
package: com.XXX.controller
第五步 啟動springboot服務，訪問http://localhost:9090/swagger-ui.html
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/71616.html
標籤：Java
上一篇：Go語言入門教程(十)之函式