swagger-ui

作者:原创时间:2022-06-01
文档

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文档

以上就是小编今天的分享了,希望可以帮助到大家。

显示全文
网络工程师考试时间 网络工程师就业前景 网络工程师的职责 网络工程师怎么考 网络工程师如何考 考网络工程师 网络工程师好学吗 网络工程师报考条件 高级网络工程师好考吗 网络工程师通过率 网络工程师考什么内容 网络工程师是干嘛的 网络工程师证书查询 计算机四级网络工程师考什么 网络工程师认证有哪些 初级网络工程师报考条件 网络工程师有什么用 网络工程师作用 软件工程师和网络工程师哪个好 四级网络工程师有用吗 网络工程师要学多久 软考网络工程师含金量 华为认证网络工程师好考吗 pmp证书难度大吗 pmp证书有用吗 pmp证书作用 system ui pmp考试题型 pmp考试时间报名时间 pmp证书编号查询 pmp认证是什么 pmp考试怎么考 pmp如何考 pmp考试 pmp学习内容 pmp考试流程 pmp好考吗 pmp考试要求 什么是pmp pmp是什么意思 pmp有用吗 pmp学什么 项目管理师pmp报考条件 考pmp认证有什么用 pmp认证作用 pmp考试需要准备多久 pmp啥证 pmp证书怎么考 pmp证书如何考