导入接口文档
登录YApi网站(网址https://yapi.pro/)
导入下图中的文件
另一个项目同理
Swagger
除了YApi之外,我们还需要使用Swagger进行API的文档生成、测试与管理。Swagger UI提供了实时的 API 测试功能,我们可以直接在网页上调用API,获取实际响应,非常方便。
配置
首先需要在pom文件中添加Swagger的相关依赖。
Knife4j是Java MVC框架集成Swagger生产API文档的增强解决方案,我们需要添加它
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j}</version>
</dependency>
然后在WebMvcConfiguration中进行基础配置
/**
* 通过knife4j生成接口文档
* @return
*/
@Bean
public Docket docket() {
log.info("准备生成接口文档...");
ApiInfo apiInfo = new ApiInfoBuilder()
.title("苍穹外卖项目接口文档")
.version("2.0")
.description("苍穹外卖项目接口文档")
.build();
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.sky.controller"))//扫描对应的包并解析
.paths(PathSelectors.any())
.build();
return docket;
}
/**
* 设置静态资源映射
* @param registry
*/
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
log.info("开始设置静态资源映射");
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
配置完成后输入配置中的网站,开始接口调试
Swagger常用注解
@Api
注解用于类级别,它的主要作用是标识该类为一个API,并为相关的API提供额外的描述信息。
@ApiOperation
注解用于方法级别
@ApiParam
注解用于描述方法参数的详细信息
@ApiResponse
和 @ApiResponses
用于描述API返回的各种HTTP状态及其含义。
@ApiModel
注解用于class级别,通常与模型类(如请求体或响应体的定义)结合使用
@ApiIgnore
注解用于标记某些类或方法不包含在Swagger生成的API文档中。
添加完成后可以看到Swagger接口文档已经改变