Swagger与knife框架生成接口文档

在项目中自动生成接口文档使用步骤

官网：https://swagger.io

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"


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);
    }
}