教育
Swagger UI 簡介
Swagger UI允許任何人都可以可視化API資源并與之交互，而無需任何實現邏輯。它是根據OpenAPI（以前稱為Swagger）規范自動生成的，具有可視化文檔，可簡化后端實現和客戶端使用。
SwaggerUI 特點
1、無依賴，UI可以在任何開發環境中使用，無論是本地還是在Web端中。
2、人性化，允許最終開發人員輕松地進行交互，并嘗試API公開的每個操作，以方便使用。
3、易于瀏覽，歸類整齊的文檔可快速查找并使用資源和端點。
4、所有瀏覽器支持，Swagger UI 在所有主要瀏覽器中均可使用，以適應各種可能的情況。
5、完全可定制，通過完整的源代碼訪問方式以所需方式設置和調整Swagger UI。
6、完整的OAS支持，可視化Swagger 2.0或OAS 3.0中定義的API。
關于swagger-ui的使用過程是怎么樣的？
導入jar包
???????????????????? ????????io.springfox ????????????springfox-swagger2 ????????????2.9.2 ???????????????????? io.springfox ????????????springfox-swagger-ui ????????????2.9.2 ????????
編寫SwaggerConfig配置文件
/**
?*/
@EnableSwagger2
@Configuration
public?class?SwaggerConfig?{
????@Bean
????public?Docket?createRestApi()?{
????????return?new?Docket(DocumentationType.SWAGGER_2)
????????????????.apiInfo(apiInfo())
????????????????.select()
????????????????//為當前包路徑,控制器類包
????????????????.apis(RequestHandlerSelectors.basePackage("com.stu.stusystem.controller"))
????????????????.paths(PathSelectors.any())
????????????????.build();
????}
????//構建?api文檔的詳細信息函數
????private?ApiInfo?apiInfo()?{
????????return?new?ApiInfoBuilder()
????????????????//頁面標題
????????????????.title("管理系統API接口文檔")
????????????????//創建人
????????????????.contact(new?Contact("cxt",?"http://localhost",?"10******[email protected]"))
????????????????//版本號
????????????????.version("1.0")
????????????????//描述
????????????????.description("系統API描述")
????????????????.build();
????}
}2）指定靜態文件地址
在swagger文件生成后需要指定下文件存放的地方。
/**
?*?設置靜態文件地址
?*/
@Component
public?class?WebConfigImpl?implements?WebMvcConfigurer?{
????@Override
????public?void?addResourceHandlers(ResourceHandlerRegistry?registry)?{
????????registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
????????registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
????}
}3）放開swagger頁面相關請求資源
比如shiro中需要設置這幾項
???????filterChainDefinitionMap.put("/v2/api-docs/**",?"anon");
????????filterChainDefinitionMap.put("/swagger-ui.html",?"anon");
????????filterChainDefinitionMap.put("/swagger-resources/**",?"anon");
????????filterChainDefinitionMap.put("/webjars/springfox-swagger-ui/**",?"anon");4）關于API文檔注解
放在Controller方法上面注解
//?tags?表示分組，頁面中的接口進行分組
@ApiOperation(value="接口名稱"?，notes="接口說明",?tags="接口屬于哪個分組",?httpMethod="接口請求方式")
//?參數說明
@ApiImplicitParams({
????@ApiImplicitParam(name="參數一",?value="對參數的說明",?required=true?[是否必須],?dataType="String")
????……
})
//?請求成功響應格式
@ApiRespones({
????@ApiResponse(code=200,?message="請求成功",?response=AjaxResponse.class)????
})放在Bean上面
@ApiModel(value?=?"這個Bean的說明") @ApiModelProperty(value?=?"這個屬性的說明",?example="1,2,3")?//?example?中的值表示這個屬性都可以返回那些值
5) swagger導出離線文檔
Swagger文檔?->?Asciidoc文檔->?Html/pdf?文檔 ->?Markdown文檔
1）導入需要的jar包
???????????????????? io.github.swagger2markup ????????????swagger2markup ????????????1.3.1 ????????
2）編寫測試類
需要在pom文件中添加Test測試類的jar支持
???????????????????? org.springframework.boot ????????????spring-boot-starter-test ????????????test ???????????????????????????? ???????????????????????????? ????????????org.junit.vintage ????????????????????junit-vintage-engine ????????????????
@ExtendWith(SpringExtension.class)//@RunWith(SpringRunner.class)???//?Junit4?開發者使用這個注解@SpringBootTest(webEnvironment?=?SpringBootTest.WebEnvironment.DEFINED_PORT)public?class?ImportSwagger?{
????@Test
????public?void?generateAsciiDocs()?throws?Exception?{
????????Swagger2MarkupConfig?config?=?new?Swagger2MarkupConfigBuilder()
????????????????.withMarkupLanguage(MarkupLanguage.MARKDOWN)?//?設置生成格式Markdown????????????????.withOutputLanguage(Language.ZH)?//?設置語言中文????????????????.withPathsGroupedBy(GroupBy.TAGS)
????????????????.withGeneratedExamples()
????????????????.withoutInlineSchema()
????????????????.build();
????????Swagger2MarkupConverter.from(new?URL("http://127.0.0.1:2020/v2/api-docs"))?//?復制到瀏覽器中可以看到JSION數據的地址????????????????.withConfig(config)
????????????????.build()
????????????????.toFile(Paths.get("src/main/resources/docs"));??//?這里注意，src前面不能有?“/”????}}結果：導出成功的Markdown文檔
以上就是小編今天的分享了，希望可以幫助到大家。
