您好,登錄后才能下訂單哦!
這篇文章主要介紹“Swagger3的優(yōu)點有哪些”,在日常操作中,相信很多人在Swagger3的優(yōu)點有哪些問題上存在疑惑,小編查閱了各式資料,整理出簡單好用的操作方法,希望對大家解答”Swagger3的優(yōu)點有哪些”的疑惑有所幫助!接下來,請跟著小編一起來學(xué)習(xí)吧!
Swagger目前最新版本是3.0.0,在Spring Boot應(yīng)用中集成Swagger3比老的Swagger2簡單多了,它提供了一個Starter組件。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
就這就可以了,簡單不?
至于有的教程說還要開啟注解@EnableOpenApi,完全不需要。因為在springfox-boot-starter-3.0.0.jar下你可以找到一個spring.factories,熟悉Spring Boot的同學(xué)都知道這個是一個Spring Boot 特有的SPI文件,能夠自動的發(fā)現(xiàn)并注冊Starter組件的配置。里面有這樣的配置:
# Auto Configure org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration
順藤摸瓜,找到總的配置類OpenApiAutoConfiguration:
@Configuration @EnableConfigurationProperties(SpringfoxConfigurationProperties.class) @ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) @Import({ OpenApiDocumentationConfiguration.class, SpringDataRestConfiguration.class, BeanValidatorPluginsConfiguration.class, Swagger2DocumentationConfiguration.class, SwaggerUiWebFluxConfiguration.class, SwaggerUiWebMvcConfiguration.class }) @AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class, HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class }) public class OpenApiAutoConfiguration { }
我們找到了關(guān)鍵的一個地方@ConditionalOnProperty注解聲明了當(dāng)springfox.documentation.enabled為true時啟用配置,而且默認(rèn)值就是true。這非常有用,Swagger僅僅建議在開發(fā)階段使用,這個正好是個開關(guān)。另外有時候我們自定義配置的時候最好把這個開關(guān)也加上:
// 自定義swagger3文檔信息 @Configuration @ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) public class Swagger3Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Swagger3接口文檔") .description("更多請咨詢felord.cn") .contact(new Contact("碼農(nóng)小胖哥", "https://felord.cn", "dax@felord.cn")) .version("1.0.0") .build(); } }
如果你想在Swagger3中加入Json Web Token,可以參考這篇文章。
最開始我們提到Swagger3不需要使用@EnableOpenApi或者@EnableSwagger2開啟,這里也能找到答案。
@Import(OpenApiDocumentationConfiguration.class) public @interface EnableOpenApi { } @Import(Swagger2DocumentationConfiguration.class) public @interface EnableSwagger2 { }
上面的兩個導(dǎo)入類都可以在OpenApiAutoConfiguration找到,所以Swagger3提供的是全自動的集成。
如果你使用了統(tǒng)一返回體封裝器來標(biāo)準(zhǔn)化Spring MVC接口的統(tǒng)一返回
/** * 返回體統(tǒng)一封裝器 * * @author n1 */ @RestControllerAdvice public class RestBodyAdvice implements ResponseBodyAdvice<Object> { @Override public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) { return !returnType.hasMethodAnnotation(IgnoreRestBody.class); } @Override public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) { if (body == null) { return RestBody.ok(); } if (Rest.class.isAssignableFrom(body.getClass())) { return body; } return RestBody.okData(body); } }
你會發(fā)現(xiàn)Swagger3會報Unable to infer base url……的錯誤,這是因為統(tǒng)一返回體影響到了Swagger3的一些內(nèi)置接口。解決方法是@RestControllerAdvice控制好生效的包范圍,也就是配置其basePackages參數(shù)就行了,這個潛在的沖突浪費我了一個多小時。
如果你使用安全框架,Swagger3的內(nèi)置接口就會訪問受限,我們需要排除掉。Spring Security是這么配置的:
@Override public void configure(WebSecurity web) throws Exception { //忽略swagger3所需要用到的靜態(tài)資源,允許訪問 web.ignoring().antMatchers( "/swagger-ui.html", "/swagger-ui/**", "/swagger-resources/**", "/v2/api-docs", "/v3/api-docs", "/webjars/**"); }
如果你使用的版本是Spring Security 5.4,你可以這么定制WebSecurity:
@Bean WebSecurityCustomizer swaggerWebSecurityCustomizer() { return (web) -> { web.ignoring().antMatchers(new String[]{"/swagger-ui.html", "/swagger-ui/**", "/swagger-resources/**", "/v2/api-docs", "/v3/api-docs", "/webjars/**"}); }; }
更加方便簡單圖片,這樣Swagger就能正常的渲染和訪問了。
到此,關(guān)于“Swagger3的優(yōu)點有哪些”的學(xué)習(xí)就結(jié)束了,希望能夠解決大家的疑惑。理論與實踐的搭配能更好的幫助大家學(xué)習(xí),快去試試吧!若想繼續(xù)學(xué)習(xí)更多相關(guān)知識,請繼續(xù)關(guān)注億速云網(wǎng)站,小編會繼續(xù)努力為大家?guī)砀鄬嵱玫奈恼拢?/p>
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點不代表本網(wǎng)站立場,如果涉及侵權(quán)請聯(lián)系站長郵箱:is@yisu.com進(jìn)行舉報,并提供相關(guān)證據(jù),一經(jīng)查實,將立刻刪除涉嫌侵權(quán)內(nèi)容。