在项目中自动生成接口文档使用步骤
Knife使用步骤:
1).在pom.xml导入坐标
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.2</version>
</dependency>
2).新建配置类
@Configuration
@EnableSwagger2
@EnableKnife4j
publlic class Knife4jConfig{
@Bean
public Docket createRestApi() {
// 文档类型
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itheima.reggie.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("瑞吉外卖") //接口文档标题
.version("1.0") //接口文档版本
.description("瑞吉外卖接口文档") //接口文档描述信息
.build();
}
}
3). 设置静态资源映射
由于Swagger生成的在线文档中,涉及到很多静态资源,这些静态资源需要添加静态资源映射,否则接口文档页面无法访问。因此需要在 WebMvcConfig类中的addResourceHandlers方法中增加如下配置。
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
4). 在LoginCheckFilter中设置不需要处理的请求路径
需要将Swagger及Knife4j相关的静态资源直接放行,无需登录即可访问,否则我们就需要登录之后,才可以访问接口文档的页面。
在原有的不需要处理的请求路径中,再增加如下链接:
"/doc.html",
"/webjars/**",
"/swagger-resources",
"/v2/api-docs"
![image-20210901171132242.png](https://img-blog.csdnimg.cn/img_convert/6dbe2e6e74f23ca81ccfbed0da1c38d8.png#clientId=u0749ac1c-d2dd-4&crop=0&crop=0&crop=1&crop=1&from=drop&id=u3cf73c30&margin=[object Object]&name=image-20210901171132242.png&originHeight=475&originWidth=1410&originalType=binary&ratio=1&rotation=0&showTitle=false&size=39471&status=done&style=none&taskId=ue2e19541-a426-46f1-bc1f-3038d9b0f1b&title=)
5).查看接口文档
经过上面的集成配置之后,我们的项目集成Swagger及Knife4j就已经完成了,接下来我们可以重新启动项目,访问接口文档,访问链接为: http://localhost:8080/doc.html
6).加入注解,加上描述信息
为了解决上述的问题,Swagger提供了很多的注解,通过这些注解,我们可以更好更清晰的描述我们的接口,包含接口的请求参数、响应数据、数据模型等。核心的注解,主要包含以下几个:
注解 | 位置 | 说明 |
---|---|---|
@Api | 类 | 加在Controller类上,表示对类的说明 |
@ApiModel | 类(通常是实体类) | 描述实体类的作用 |
@ApiModelProperty | 属性 | 描述实体类的属性 |
@ApiOperation | 方法 | 说明方法的用途、作用 |
@ApiImplicitParams | 方法 | 表示一组参数说明 |
@ApiImplicitParam | 方法 | 用在@ApiImplicitParams注解中,指定一个请求参数的各个方面的属性 |
注解测试
1). 实体类
可以通过 @ApiModel , @ApiModelProperty 来描述实体类及属性
@Data
@ApiModel("学生")
public class Student implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty("主键")
private Long id;
//学生姓名
@ApiModelProperty("学生姓名")
private String name;
//学生年龄
@ApiModelProperty("学生姓名")
private Integer age;
//学生性别
@ApiModelProperty("学生性别")
private String sex;
}
2).Controller类及其中的方法
描述Controller、方法及其方法参数,可以通过注解: @Api, @APIOperation, @ApiImplicitParams, @ApiImplicitParam
@RestController
@RequestMapping("/student")
@Api(tags = "学生相关接口")
public class StudentController {
@Autowired
private StudentService studentService;
/**
* 新增学生
* @param Student
* @return
*/
@PostMapping
@ApiOperation(value = "新增学生接口")
public void save(@RequestBody Student student){
studentService.save(student);
}
/**
* 删除学生
* @param id
* @return
*/
@DeleteMapping
@ApiOperation(value = "学生删除接口")
public void delete(@RequestParam Long id){
studentService.remove(id);
}
}