在线接口文档使用

aslyfox
219 阅读4分钟

1.Swagger介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

它的主要作用是：

  • 使得前后端分离开发更加方便，有利于团队协作
  • 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
  • 功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，就可以非常简单快捷的使用Swagger啦。

2.项目中集成Swagger

  1. 关键依赖 image.png

  2. 核心配置类

    1. 位置：com.ruoyi.web.core.config.SwaggerConfig
    2. 请设计prompt提示词，来阅读以下代码
package com.ruoyi.web.core.config;

import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.ruoyi.common.config.RuoYiConfig;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

/**
* Swagger2的接口配置
*
* @author ruoyi
*/
@Configuration
public class SwaggerConfig
{
    /** 系统基础配置 */
@Autowired
    private RuoYiConfig ruoyiConfig;

    /** 是否开启swagger */
@Value("${swagger.enabled}")
    private boolean enabled;

    /** 设置请求的统一前缀 */
@Value("${swagger.pathMapping}")
    private String pathMapping;

    /**
* 创建API
*/
@Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.OAS_30)
                // 是否启用Swagger
.enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
.select()
                // 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
 // .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
 // 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
                .build()
                /* 设置安全模式，swagger可以设置访问token */
.securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                .pathMapping(pathMapping);
    }

    /**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes()
    {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
        return apiKeyList;
    }

    /**
* 安全上下文
*/
private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
* 添加摘要信息
*/
private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
                // 设置标题
.title("标题：若依管理系统_接口文档")
                // 描述
.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                // 作者信息
.contact(new Contact(ruoyiConfig.getName(), null, null))
                // 版本
.version("版本号:" + ruoyiConfig.getVersion())
                .build();
    }
}

3.集成Knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

4.常见注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解说明
@Api用在类上，描述Controller的作用
@ApiOperation用在方法上，说明方法的用途、作用
@ApiParam用在方法的参数上，描述单个形参的含义，适用于简单场景
@ApiImplicitParam用在方法上，描述单个形参的含义，适用于参数复杂或者详细描述参数的场景
@ApiModel用在类上，用对象来接收参数或者返回参数，描述类的含义
@ApiModelProperty用在类的属性上，用对象来接收参数或者返回参数，描述字段的含义

使用ai快速生成

我们熟悉了这些注解之后，我们可以让AI协助我们快速完成注解的编写：

Prompt

把整个NursingProjectController类给AI，然后在最后添加上一句话：

帮我给上述代码添加上swagger注解说明，要求每个参数也要进行说明，如：@Api、@ApiOperation、@ApiParam

请求体参数快速生成

一般的形参，如：id，status等这些，在controller的方法可以使用@ApiParam或者@ApiImplicitParam注解进行描述，如果接口是post、put请求，可能接收的是一个对象作为请求体参数，上面两个注解并不能很好的进行描述，这个时候需要使用新的注解：@ApiModel和@ApiModelProperty

比如，在新增护理项目的时候，接收的参数为NursingProject实体类，我们可以用这些注解在实体类中进行描述

如下代码：

package com.ruoyi.serve.domain;

import java.math.BigDecimal;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import com.ruoyi.common.annotation.Excel;
import com.ruoyi.common.core.domain.BaseEntity;

/**
* 护理项目对象 nursing_project
*
* @author ruoyi
* @date 2024-06-09
*/
@ApiModel("护理项目实体")
public class NursingProject extends BaseEntity
{
    private static final long serialVersionUID = 1L;

    /** 编号 */
 @ApiModelProperty(value = "主键ID")
    private Long id;

    /** 名称 */
@Excel(name = "名称")
    @ApiModelProperty(value = "名称")
    private String name;

    /** 排序号 */
@Excel(name = "排序号")
    @ApiModelProperty(value = "排序号")
    private Long orderNo;

    /** 单位 */
@Excel(name = "单位")
    @ApiModelProperty(value = "单位")
    private String unit;

    /** 价格 */
@Excel(name = "价格")
    @ApiModelProperty(value = "价格")
    private BigDecimal price;

    /** 图片 */
@Excel(name = "图片")
    @ApiModelProperty(value = "图片")
    private String image;

    /** 护理要求 */
@Excel(name = "护理要求")
    @ApiModelProperty(value = "护理要求")
    private String nursingRequirement;

    /** 状态（0：禁用，1：启用） */
@Excel(name = "状态", readConverterExp = "0：禁用，1：启用")
    @ApiModelProperty(value = "0：禁用，1：启用")
    private Integer status;

    // set  get 方法省略
}
avatar
文章
阅读
粉丝