Yapi、Swagger笔记

Yapi介绍

一个高效、易用、功能强大的api管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务

使用环境

需要额外配置，暂时先放下

可使用插件

• UploadToYapi

Swagger/Knife4j

使用Swagger只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等

Swagger

一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务

使用步骤

1. 引入依赖

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
dependency>

2. 编写配置类

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
            	.apiInfo(buildApiInto())
            	.select()
            	// 要扫描的API(Controller)基础包
            	.api(RequestHandlerSelectors.basePackage("com.xlrong"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo buildApiInfo() {
        Contact contact = new Cpntact("", "", "");
        
        return new ApiInfoBuilder()
            .title("...文档")
            .description("...api")
            .contact(contact)
            .version("1.0.0")
            .build();
    }
}

3. 启动

http://ip:port/swagger-ui.html

常用注解

• @Api: 用在请求的类上，例如Controller，表示对类的说明
• @ApiModel: 用在类上，通常是实体类，表示一个返回响应数据的信息
• @ApiModelProperty: 用在属性上，描述响应类的属性
• @ApiOperation: 用在请求的方法上，说明方法的用途、作用
• @ApiImplicitParams: 用在请求的方法上，表示一组参数说明
• @ApiImplicitParam: 用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

Knife4j

使用步骤

1. 导入knife4j的maven坐标

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-spring-boot-starterartifactId>
    <version>3.0.3version>
dependency>

2. WebMvcConfig中导入knife4j相关配置类

@EnableSwagger2
@EnableKnife4j

3. WebMvcConfig中设置静态资源，否则接口文档页面无法访问

@Bean
public Docket createRestApi() {
    // 文档类型
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("packegePath.to.controller"))
        .paths(PathSelectors.any())
        .build();
}

private ApiInfo aopInfo() {
    return new ApiInfoBuilder()
        .title("title")
        .version("1.0")
        .description("接口文档")
        .build();
}

4. 在WebMvcConfig的addResourceHandlers()设置静态资源映射

registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/MEAT-INF/resources/webjars/");
    

5. 在过滤器中设置不需要处理的请求路径

/doc.html
/webjars/**
/swagger-resources
/v2/api-docs

6. 访问

http://ip:port/doc.html