Swagger2 和 Swagger3在线文档的使用

Swagger2在线文档的使用

注意：

• 我今天发现Swagger不兼容JDK9以上；因为Swagger依赖javax这个包，JDK9以上的javax包变成了jakarta包。
• 解决办法放在了下文中的 “Swagger3在线文档的使用”

案例：springboot整合Swagger2

1、首先创建一个springboot工程，要使用Swagger就要先在pom文件内导入依赖

 <!--swagger依赖-->
 <!--Swagger2-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.0</version>
 </dependency>
 <!--Swagger-ui界面-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.0</version>
 </dependency>

2、在springboot工程内的项目运行无误后，创建配置类SwaggerConfig

@Configuration // 配置类
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

  /**
   * 配置了Swagger的Docket的Bean实例
   * 可以有多个
   * @return
   */
  @Bean
  public Docket docket(Environment environment) {
    // 获取项目环境
    // 设置要显示的Swagger2环境
    Profiles profiles = Profiles.of("dev");
    // 监听    通过environment.acceptsProfiles判断是否处在自己设定的环境
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // Select a spec默认值
        .groupName("茶碗儿")
        // 是否开启swagger2
        // .enable(false)
        // 监听
        .enable(flag)
        .select()
        // RequestHandlerSelectors   配置要扫描接口的方式
        // basePackage               指定扫描的包
        // any                       扫描全部
        // none                      不扫描
        // withClassAnnotation       扫描类上的注解，参数是一个注解的反射对象
        // withMethodAnnotation      扫描方法上的注解
        .apis(RequestHandlerSelectors.basePackage("com.changgou.controller"))
        // 过滤路径
        // .paths(PathSelectors.ant("/changgou/**"))
        .build();
  }

  @Bean
  public Docket docket1(Environment environment) {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("花生糖");
  }

  // 配置Swagger2信息
  private ApiInfo apiInfo() {
    // 作者信息
    Contact contact = new Contact("茶碗儿", "https://www.cnblogs.com/chawaner/", "*******@qq.com");

    return new ApiInfo(
        // 大标题
        "畅购商城",
        // 描述
        "畅购商城在线API",
        // 版本
        "v1.0",
        // 服务组织url
        "https://www.cnblogs.com/chawaner/",
        // 作者信息
        contact,
        // 开源版本号
        "Apache 2.0",
         开源版本url
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList<VendorExtension>());
  }
}

3、在JavaBean中加上注解

@ApiModel(description = "Result", value = "Result")
@Data // lombok注解
public class Result<T> implements Serializable {

  @ApiModelProperty(value = "执行是否成功,true:成功,false:失败", required = true)
  private boolean flag; // 是否成功

  @ApiModelProperty(value = "返回状态码,20000:成功,20001:失败,20002:用户名或密码错误,20003:权限不足,20004:远程调用失败,20005:重复操作,20006:没有对应的抢购数据", required = true)
  private Integer code; // 返回码

  @ApiModelProperty(value = "提示信息", required = true)
  private String message; // 返回消息

  @ApiModelProperty(value = "逻辑数据", required = true)
  private T data; // 返回数据

  public Result(boolean flag, Integer code, String message, Object data) {
    this.flag = flag;
    this.code = code;
    this.message = message;
    this.data = (T) data;
  }

  public Result(boolean flag, Integer code, String message) {
    this.flag = flag;
    this.code = code;
    this.message = message;
  }

  public Result() {
    this.flag = true;
    this.code = StatusCode.OK;
    this.message = "操作成功!";
  }
}

4、在controller类中加入注解

@Api(
    value = "用户品牌操作",
    tags = {"用户品牌操作接口"})
@RestController
@RequestMapping(value = "/brand")
@CrossOrigin // 跨域访问：域名、端口、协议不一致
public class BrandController {

  @Autowired private BrandService brandService;

  /** 查询所有 */
  @ApiOperation("查询所有品牌信息")
  @GetMapping
  public Result<List<Brand>> findAll() {
    // 查询所有品牌信息
    List<Brand> brands = brandService.findAll();
    // 响应结果封装
    return new Result<List<Brand>>(true, StatusCode.OK, "查询品牌集合成功!", brands);
  }

  /** 根据主键id查询 */
  @ApiOperation("据主键id查询") // 接口 放在方法上
  @GetMapping(value = "/{id}")
  public Result<Brand> findById(
      @ApiParam(value = "传入的id") @PathVariable(value = "id") Integer id) {
    Brand brand = brandService.findById(id);
    return new Result<Brand>(true, StatusCode.OK, "根据id查询品牌成功!", brand);
  }

  /**
   * 增加品牌
   *
   * @param brand
   */
  @ApiOperation("增加品牌")
  @PostMapping
  public Result add(@ApiParam(value = "要增加的品牌信息") @RequestBody Brand brand) {
    brandService.add(brand);
    return new Result(true, StatusCode.OK, "添加品牌成功!");
  }

  /**
   * 根据ID修改品牌数据
   *
   * @param id
   * @param brand
   * @return
   */
  @ApiOperation("根据ID修改品牌信息")
  @PutMapping(value = "/{id}")
  public Result update(
      @ApiParam(value = "输入的id", example = "1") @PathVariable(value = "id") Integer id,
      @ApiParam(value = "brand") @RequestBody Brand brand) {
    brand.setId(id);
    brandService.update(brand);
    return new Result(true, StatusCode.OK, "根据ID修改品牌成功!");
  }

  /**
   * 根据ID删除品牌数据
   *
   * @param id
   */
  @ApiOperation("根据ID删除品牌")
  @DeleteMapping(value = "/{id}")
  public Result delete(@ApiParam(value = "输入的id") @PathVariable(value = "id") Integer id) {
    brandService.delete(id);
    return new Result(true, StatusCode.OK, "根据ID删除品牌数据成功!");
  }

  /** 根据品牌信息多条件搜索 */
  @ApiOperation("根据品牌信息多条件搜索")
  @PostMapping(value = "/search")
  public Result<List<Brand>> findList(@ApiParam(value = "查询条件") @RequestBody Brand brand) {
    List<Brand> brands = brandService.findList(brand);
    return new Result<List<Brand>>(true, StatusCode.OK, "根据品牌信息多条件搜索成功!", brands);
  }

  /**
   * 分页查询实现
   *
   * @param page：当前页
   * @param size：每页显示条数
   * @return
   */
  @ApiOperation("分页查询实现")
  @GetMapping(value = "/search/{page}/{size}")
  public Result<PageInfo<Brand>> findPage(
      @ApiParam(value = "当前页") @PathVariable(value = "page") Integer page,
      @ApiParam(value = "显示的条数") @PathVariable(value = "size") Integer size) {
    PageInfo<Brand> pageInfo = brandService.findPage(page, size);
    return new Result<PageInfo<Brand>>(true, StatusCode.OK, "分页查询成功!", pageInfo);
  }

  /**
   * 分页查询 + 条件搜索
   *
   * @param brand:搜索条件
   * @param page:当前页
   * @param size:每页显示条数
   * @return
   */
  @ApiOperation("分页查询 + 条件搜索")
  @PostMapping(value = "/search/{page}/{size}")
  public Result<PageInfo<Brand>> findPage(
      @ApiParam(value = "查询条件") @RequestBody Brand brand,
      @ApiParam(value = "当前页") @PathVariable(value = "page") Integer page,
      @ApiParam(value = "显示的条数") @PathVariable(value = "size") Integer size) {
    PageInfo<Brand> pageInfo = brandService.findPage(brand, page, size);
    return new Result<PageInfo<Brand>>(true, StatusCode.OK, "分页查询成功!", pageInfo);
  }
}

5、配置文件application.yml中配端口号和端口扫描

注意：
1.端口号是从浏览器打开swagger-ui时的端口
2.配置端口扫描是为了设置在开发时开启swagger在线文档，在产品发布后不开启
3.注意看上面的SwaggerConfig配置类里面的：Profiles profiles = Profiles.of("dev");
扫描包含dev的配置文件，所以打开ui界面就得18082端口

application.yml

#端口的配置
server:
  port: 18081
      
#设置对dev的端口开启swagger
#本来是访问http://localhost:18081/swagger-ui.html打开swagger-ui界面
#配置了这个之后，打开swagger-ui界面就要访问http://localhost:18082/swagger-ui.html
spring:
  profiles:
    active: dev

application-dev.yml

server:
  port: 18082

application-pro.yml

server:
  port: 18083

Swagger常用注解

位置	注解	说明
controller	@Api	对请求类的说明
方法	@ApiOperation	方法的说明
方法	@ApiImplicitParams、@ApiImplicitParam	方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
方法	@ApiResponses、@ApiResponse	方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明
对象	@ApiModel	用在JavaBean类上，说明JavaBean的 用途
对象	@ApiModelProperty	用在JavaBean类的属性上面，说明此属性的的含议

@Api：

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
	tags="说明该类的作用"
	value="该参数没什么意义，所以不需要配置"

示例1：

@Api(tags="订单模块")
@Controller
public class OrderController {

}

@Api其他属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

@ApiOperation:

@ApiOperation："用在请求的方法上，说明方法的作用"
	value="说明方法的作用"
	notes="方法的备注说明"

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
	    name：参数名
	    value：参数的说明、描述
	    required：参数是否必须必填
	    paramType：参数放在哪个地方
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"	   
	    defaultValue：参数的默认值

示例2：

@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation(value="用户登录",notes="随边说点啥")
	@ApiImplicitParams({
		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}
}

@ApiResponses、@ApiResponse：方法返回值的状态码说明

@ApiResponses：方法返回对象的说明
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

示例3：

@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation("获取用户信息")
	@ApiImplicitParams({
		@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
	}) 
	@ApiResponses({
		@ApiResponse(code = 200, message = "请求成功"),
		@ApiResponse(code = 400, message = "请求参数没填好"),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
	}) 
	@ResponseBody
	@RequestMapping("/list")
	public JsonResult list(@RequestParam String userId) {
		...
		return JsonResult.ok().put("page", pageUtil);
	}
}

@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述

@ApiModel的用途有2个：
当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。

Swagger3在线文档的使用

• 导入依赖
• 配置文件
• Swagger配置文件
• 注意这几个注解
• 访问页面

导入依赖

Swagger3导入这一个依赖就够了

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

yml配置文件

# swagger配置
knife4j:
  enable: true
  setting:
    language: zh_cn
springdoc:
  swagger-ui:
    # 修改Swagger UI路径
#    path: /swagger-ui.html
    # 开启Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路径
    path: /v3/api-docs
    # 开启api-docs
    enabled: true
  group-configs:
    - group: 'default'
      # 配置需要生成接口文档的接口路径
      paths-to-match: '/**'
      # 配置需要生成接口文档的扫描包
      packages-to-scan: com.chawaner.ryh.core.controller

Swagger配置类

/**
 * @Author TeaBowl
 * @Date 2024/2/22 1:43
 * @Version 1.0
 * Swagger配置类
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI swaggerOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("融易汇")
                        //描叙
                        .description("我的API文档")
                        //版本
                        .version("v1")
                        //作者信息，自行设置
                        .contact(new Contact().name("茶碗儿").email("132192**67@qq.com").url("https://www.baidu.com"))
                        //设置接口文档的许可证信息
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }

}

注解

• @ApiModel和@ApiModelProperty这两个注解就不要用了
• @Schema可以代替@ApiModel和@ApiModelProperty

pojo实体类上的几个注解

注意Conttoller实体类上的几个注解

• @Schema：用于描述类的属性，description为描叙，defaultValue为默认值，example为举例子，hidden为忽略。
• @Tag：用于对API接口进行标记和分组。
• @Operation：用于对API接口方法进行详细的操作描述，method为方法，summary为简介，description为描叙。
• @Parameter：用于指定操作的参数列表。

核心注解

访问页面

• swagger：http://地址:端口/swagger-ui/index.html
• Knife4j：http://地址:端口/doc.html