教育
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文档
以上就是小编今天的分享了，希望可以帮助到大家。
