Swagger-使用教程(详细)

Swagger

Swagger官网:https://swagger.io/

Swagger是一款 RESTful 风格的 Web 服务框架

那么问题来了 什么是RESTful？

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或 JSON格式定义。

1.导入依赖

 <dpendency>
           <groupId>com.github.xiaoymin</groupId>
           <artifactId>knife4j-spring-boot-starter</artifactId>
           <version>3.0.3</version>
</dependency>

2.编写Swagger配置类

@Configuration //配置类
@EnableSwagger2 //启⽤Swagger
public class SwaggerConfig {
    /**
     * 构建⽂档的基本信息
     */
    public ApiInfo createApi() {
        return new ApiInfoBuilder().
                // 设置页面标题
                        title("xxx项⽬的接⼝⽂档")
                // 设置接口描述
                .description("xxx项⽬是")
                // 设置联系方式
                .contact(new Contact("name", "https://blog.csdn.net/weixin_51779902?spm=1010.2135.3001.5343",
                        "0000@qq.com"))
                // 设置版本
                .version("1.0")
                //构建
                .build();
    }
    /**
     * 就是ioc创建实例 修饰⽅法 ⽅法必须返回对象
     */
    @Bean //等同于<bean> 配合@Configuration 会吧⽅法的返回值存储到IOC容器
    public Docket createDocket() {
        //SWAGGER_2:swagger版本  指定构建api文档的详细信息的方法：apiInfo()
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(createApi())
                //   RequestHandlerSelectors选择类注解方式 生成指定注解文档
                .select().apis(RequestHandlerSelectors.
                        withClassAnnotation(Api.class)).build();
    }
}

3.配置实体类

@ApiModelProperty(value = "主键" ) //修饰实体类的属性 默认是false
@ApiModelProperty(value = "账户",required =true ) //修饰实体类的属性
@ApiModelProperty(value = "密码",required =true ) //修饰实体类的属性

4.使用Swagger

@RestController
@RequestMapping("/api/manger/")
@Api(tags = "管理员的相关操作") //修饰类，为类加接口说明
public class MangerController {
    @Autowired
    private MangerService service;

    @ApiOperation(value = "新增",notes = "实现账户的新增")//修饰⽅法，为⽅法加说明
    @PostMapping("save.do")
    public R save(Manger manger){
       return service.save(manger);
    }

    @ApiOperation(value = "查询所有",notes = "实现所有账户的数据")
    @GetMapping("all.do")
    public R all(){
        return service.all();
    }
}

4.在application.yml配置

spring:
  profiles:
    active: dev
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER  #防⽌swagger报错

5.运行测试

加账户密码

# swagger配置密码
knife4j:
  # 开启增强配置
  enable: true
      # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: test
    # Basic认证密码
    password: 123

http://localhost:8080/doc.htm

6.效果

上传文件注解:@RequestPart

public String upload(@RequestPart MultipartFile file, HttpServletRequest request) throws IOException {

Swagger常⽤注解：

@Api(tags = “说明信息”) 修饰类，控制层的类，为类加注释内容，通过tags属性

@ApiOperation(value = “⽅法说明”,notes = “⽅法详细介绍”) 修饰⽅法，映射⽅法，为⽅法加注释内容

@ApiParam(value=“参数的说明”) 修饰⽅法的参数，为参数加说明

@ApiModelProperty(value = “参数的说明”,required = 是否必须传递) 修饰实体类的属性