1.Maven依赖引入
<!-- swagger3:访问路径http://ip:port/swagger-ui/index.html-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.SwaggerConfig配置类
package com.zhigong.heavenearth.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @author 田治功
* @description Swagger配置类
* @date 2021-10-31 1:36
*/
@EnableOpenApi//该注解是Springfox-swagger框架提供的使用Swagger注解,该注解必须加
@EnableKnife4j//该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解,否则可以不用加
@Configuration
public class SwaggerConfig {
/**
* 接口构建器
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.zhigong.heavenearth.controller"))
.paths(PathSelectors.any())
.build()
.groupName("治功")
.enable(true);
}
/**
* Api页面信息配置
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("技术学习实践整合")
.description("新技术整合学习及配置案例DEMO")
.contact(new Contact("治功", "https://juejin.cn/user/2806404106423112", "邮箱"))
.version("V1.0")
.build();
}
}
3.Controller
package com.zhigong.heavenearth.controller;
import com.zhigong.heavenearth.common.Result;
import com.zhigong.heavenearth.dto.SkillStudyPlanDTO;
import com.zhigong.heavenearth.service.SkillStudyPlanService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
/**
* @author 田治功
* @description 技术学习规划表控制器
* @date 2021-10-31 1:36
*/
@Api(tags = "技术学习规划表")
@RestController
@RequestMapping("/skillStudyPlan")
public class SkillStudyPlanController {
@Resource
private SkillStudyPlanService skillStudyPlanService;
@ApiOperation("插入技术学习规划")
@PostMapping("insertPlan")
public Result insertPlan(@RequestBody SkillStudyPlanDTO skillStudyPlanDTO) {
return skillStudyPlanService.insertPlan(skillStudyPlanDTO);
}
@ApiOperation("查询所有技术学习规划")
@GetMapping("selectAll")
public Result selectAll() {
return skillStudyPlanService.selectAll();
}
}
4.常用注解
注解 | 说明 |
---|---|
@Api | 模块配置,用在Controller类上,描述Api接口 |
@ApiOperation | 接口配置,用在方法上,描述接口方法 |
@ApiParam | 方法参数配置,用在入参中或注解中 |
@Apilgnore | 忽略此接口不生成文档 |
@ApiModel | 用于类,表示对类进行说明,描述一个Model的信息 |
@ApiModelProperty | 用于属性,表示对类中变量的说明,描述一个model的属性 |
@ApiImplicitParams | 用在方法上包含一组参数说明 |
@ApiImplicitParam | 用来注解来给方法入参增加说明 |
@ApiResponses | 用于表示一组响应结果 |
@ApiResponse | 用在@ApiResponses中,一般用于表达一个错误的响应信息 |
5.接口文档界面
使用浏览器访问http://host:port/swagger-ui/index.html即可打开接口文档界面
6.Knife4j增强方案
-
引入Maven依赖
<!-- knife4j:swagger增强方案,使用doc布局方式 --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>
-
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,已在上述的SwaggerConfig配置类中配置了Swagger,故无需单独为Knife4j配置
-
浏览器输入地址:http://host:port/doc.html即可打开接口文档界面