springboot之swagger快速啟動
springboot之swagger快速啟動
簡介
介紹
可能大家都有用過swagger,可以通過ui頁面顯示介面資訊，快速和前端進行聯調。
沒有接觸的小夥伴可以參考官網文章進行了解下demo頁面。
多應用
當然在單個應用大家可以配置SwaggerConfig類載入下buildDocket,就可以快速構建好swagger了。
程式碼大致如下：
/** * Swagger2配置類 * 在與spring boot整合時，放在與Application.java同級的目錄下。 * 通過@Configuration註解，讓Spring來載入該類配置。 * 再通過@EnableSwagger2註解來啟用Swagger2。 */ @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 建立API應用 * apiInfo() 增加API相關資訊 * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現， * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。 * * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller")) .paths(PathSelectors.any()) .build(); } /** * 建立該API的基本資訊（這些基本資訊會展現在文件頁面中） * 訪問地址：http://專案實際地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2構建RESTful APIs") .description("更多請關注http://www.baidu.com") .termsOfServiceUrl("http://www.baidu.com") .contact("sunf") .version("1.0") .build(); } }
模組化-Starter
緣由
有開發過微服務的小夥伴應該體會過。當微服務模組多的情況下，每個模組都需要配置這樣的一個類進行載入swagger。造成每個模組都存在大致一樣的SwaggerConfig,極端的情況下，有些朋友複製其他模組的SwaggerConfig進行改造之後，發現仍然載入不出swagger的情況，造成明明是複製的，為何還載入不出，排查此bug及其費時間。
在此之上，可以構建出一個swagger-starter模組，只需要引用一個jar，載入一些特殊的配置，就可以快速的使用到swagger的部分功能了。
設計
建立模組swagger-spring-boot-starter
功能大致如下：
- 載入SwaggerConfig。
- 通過配置化配置swagger。
- Enable載入註解。
1. 建立SwaggerConfig
SwaggerConfig和之前的一致，只是裡面的配置需要外部化。
@Configuration @PropertySource(value = "classpath:swagger.properties", ignoreResourceNotFound = true, encoding = "UTF-8") @EnableConfigurationProperties(SwaggerProperties.class) public class SwaggerConfig { @Resource private SwaggerProperties swaggerProperties; @Bean public Docket buildDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) .select() .apis(RequestHandlerSelectors.basePackage("")) .paths(PathSelectors.any()) .build(); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title(swaggerProperties.getTitle()) .description(swaggerProperties.getDescription()) .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl()) .contact(new Contact("skyworth", swaggerProperties.getTermsOfServiceUrl(), "")) .version(swaggerProperties.getVersion()) .build(); } }
2. 建立SwaggerProperties 配置相關
配置通過@PropertySource註解載入resources目錄下的swagger.properties。
建立SwaggerProperties配置類,這個類裡包含了一般swagger初始化要使用的一些常用的屬性，如掃描包路徑、title等等。
@Data
@ToString
@ConfigurationProperties(SwaggerProperties.PREFIX)
public class SwaggerProperties {
public static final String PREFIX = "swagger";
/**
* 文件掃描包路徑
*/
private String basePackage = "";
/**
* title 如: 使用者模組系統介面詳情
*/
private String title = "深蘭雲平臺系統介面詳情";
/**
* 服務檔案介紹
*/
private String description = "線上文件";
/**
* 服務條款網址
*/
private String termsOfServiceUrl = "https://www.deepblueai.com/";
/**
* 版本
*/
private String version = "V1.0";
}做好這兩件事情基本大工搞成了，為了更好的使用配置，在idea裡和官方starter包一樣，我們還需要配置一個additional-spring-configuration-metadata.json,讓我們自己的配置也具有提示的功能，具體介紹請產考：配置提示 配置提示 配置提示 配置提示 配置提示 ...
3. 載入SwaggerConfig等特性
因為是starter模組，可能他人的專案目錄和starter模組的目錄不一致，導致載入不到SwaggerConfig類，我們需要使用spring.factories把SwaggerConfig類裝載到spring容器。
resources/META-INF
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
io.purge.swagger.SwaggerConfig當然本次基於Enable方式去載入SwaggerConfig。
建立@EnableSwaggerPlugins註解類，使用@Import(SwaggerConfig.class)將SwaggerConfig匯入大工搞成。
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(SwaggerConfig.class)
@EnableSwagger2
public @interface EnableSwaggerPlugins {
}使用
新增依賴
把自己編寫好的swagger通過maven打包，自己專案引用。
<dependency>
<groupId>com.purge.swagger</groupId>
<artifactId>swagger-spring-boot-starter<factId>
<version>0.1.0.RELEASE</version>
</dependency>配置swagger.properties檔案
在自己專案模組的
resources目錄下 建立swagger.properties配置swagger.properties 大致配置如下
swagger.basePackage="swagger掃描專案包路徑"
swagger.title="swagger網頁顯示標題"
swagger.description="swagger網頁顯示介紹"啟動類新增
@EnableSwaggerPlugins註解。
@EnableSwaggerPlugins
@SpringBootApplication
public class FrontDemoApplication {
public static void main(String[] args) {
SpringApplication.run(FrontDemoApplication.class, args);
}
}訪問http://ip:埠/swagger-ui.html檢查swagger-ui是否正常。
總結
簡單的starter程式碼編寫可以減少新模組的複雜性，只需要簡單的配置就可以使用相應的特性，減少複製程式碼不必要的錯誤。
示例程式碼地址: swagger-spring-boot