swagger ui 配置整合

一、swagger简介

        官网：https://swagger.io/

1、认识swagger
        swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RestFul风格的web服务，总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器断的代码，允许API来始终保持同步。

2、作用：

• 接口的文档在线自动生成。
• 功能测试。

3、Swagger是一组开源项目，其中主要要项目如下：

• Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
• Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
• Swagger-js: 用于JavaScript的Swagger实现。
• Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
• Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
• Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、springboot整合swagger ui

1.在maven项目的pom文件中导入相关的依赖 

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.编写配置文件

        在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;

@Configuration   //配置类，启动时加载此类
@EnableSwagger2  //开启 swagger2 的自动配置
public class SwaggerConfig{
    @Bean
    public Docket customDocket() {
        //创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  // 配置基本信息
                .select()  // 设置扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.yxuan.springboot.controller"))//扫描的包路径
                .build()  //构建Docket对象
                .globalOperationParameters(this.getParameterList()); //配置全局请求头信息
    }


    /**
     * 基本信息设置
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("志愿护航接口文档")  // 标题
                .version("1.0.0")  // 版本
                .build();   //构建Docket对象
    }


    /**
     * 添加head参数配置
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder(); //创建一个参数构建器。
        List<Parameter> pars = new ArrayList<Parameter>();  //创建一个参数列表。
        clientIdTicket.name("token").description("token令牌")  //设置参数名称和描述信息。
                .modelRef(new ModelRef("string"))  //设置参数类型为字符串。
                .parameterType("header")  //设置参数的位置为header。
                .required(false).build(); //设置参数是否必填，这里设置为false，表示不是必填参数。
        pars.add(clientIdTicket.build()); //将构建好的参数添加到参数列表中。
        return pars; //返回参数列表。
    }
}

3.在model实体类中添加注解

•         在实体类上方添加注解 @ApiModel ，标明实体类名称
•         在每个参数上方添加注解 @ApiModel ，标明参数名称

/**
 * 
 * @author zchao
 *    CharacteristicSpecialty实体类
 * @date 2023-05-09 11:17:05
 */
@Data
@ApiModel(description = "特色专业")
@JsonIgnoreProperties(value = { "hibernateLazyInitializer", "handler" })
public class CharacteristicSpecialty implements Serializable{

	  private static final long serialVersionUID = 1L;
	
	  @ApiModelProperty(value = "")
	  private Integer id;
	  @ApiModelProperty(value = "院校id")
	  private Integer schoolId;
	  @ApiModelProperty(value = "类型")
	  private String techType;
	  @ApiModelProperty(value = "学科名")
	  private String specialtyName;


}

4.在controller层添加注解   

•         在controller类上方添加注解 @Api ，标注名称
•         在具体的方法上方添加注解 @ApiOperation ，标明方法名称，作用等
•         在具体的方法上方添加注解  @ApiImplicitParams ，可以设置方法单独的请求头信息

package com.yxuan.springboot.controller;

import com.yxuan.springboot.model.Information;
import com.yxuan.springboot.util.TencentCOSUploadFileUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.Controller;
import org.springframework.web.multipart.MultipartFile;
import javax.servlet.http.HttpServletRequest;

/**
 * 
 * @author zchao
 *   Information控制器
 * @date 2023-05-14 20:40:39
 */
@Slf4j
@Controller
@Api(tags = "资讯表")
@RequestMapping(value = "/information")
public class InformationController extends BaseController<Information>{

    /**
      * @className: InformationController.java
      * @methodName: upload
      * @effect: 文件上传腾讯云存储+
      * @author: JingxuanFan
      * @date: 2023/5/15 9:47
      **/
//    name：请求头的名称   value：请求头的描述信息  required：请求头是否必填    dataType：请求头的数据类型   paramType：请求头的类型
    @ApiOperation(value = "上传文件", notes = "将文件上传到腾讯云存储中",httpMethod = "POST")
    @ApiImplicitParams({@ApiImplicitParam(name = "userId", value = "用户登入的Id", required = true, dataType = "string", paramType = "header")})
    @PostMapping("/addFile")
    @ResponseBody
    public String upload(@RequestParam("file") MultipartFile file, HttpServletRequest request){
        try {
            if (null == file) {
                return "文件为空";
            }
            //在请求头中获取用户登入的Id
            String id = request.getHeader("userId");
            //调用工具类中上传文件的方法
            String filePath = TencentCOSUploadFileUtil.uploadfile(file,id);
            return "上传成功，访问地址为:"+filePath;
        }catch (Exception e){
            log.error(e.getMessage());
            return "addFileError";
        }
    }
}

三、注解详解

1、@Api：用于描述整个API接口信息，包括标题、描述、版本等。（常用）

• value：API接口的标题。
• description：API接口的描述。
• version：API接口的版本号。
• tags：API接口的标签，可以有多个。

示例：@Api(value = "用户管理接口", description = "提供用户的增删改查功能", tags = {"用户管理"})

2、@ApiOperation：用于描述API接口中的某个方法的信息，包括方法名、描述、请求方式等。（常用）

• value：API接口方法的名称。
• notes：API接口方法的描述。
• httpMethod：API接口方法的请求方式，如GET、POST等。
  • GET：用于获取资源。
  • POST：用于创建资源。
  • PUT：用于更新资源。
  • DELETE：用于删除资源。
  • PATCH：用于部分更新资源。
  • HEAD：类似于GET请求，但只获取资源的头部信息，用于检查资源是否存在或是否被修改。
• response：API接口方法的返回类型。

示例：@ApiOperation(value = "根据用户ID获取用户信息", notes = "根据用户ID获取用户信息", httpMethod = "GET", response = User.class)

3、@ApiParam：用于描述API接口中的参数信息。（常用）

• name：参数名称。
• value：参数的描述。
• required：参数是否必须。
• dataType：参数的数据类型。
• paramType：参数的类型，如path、query、body等。

示例：@ApiParam(name = "userId", value = "用户ID", required = true, dataType = "int", paramType = "path")

4、@ApiResponse：用于描述API接口方法的返回信息。

• code：返回状态码。
• message：返回消息。
• response：返回类型。

示例：@ApiResponse(code = 200, message = "操作成功", response = User.class)

5、@ApiResponses：用于描述API接口方法的多个返回信息。参数如下：
value：@ApiResponse注解数组。

示例：

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "操作成功", response = User.class),
    @ApiResponse(code = 400, message = "请求参数错误", response = Error.class),
    @ApiResponse(code = 500, message = "服务器内部错误", response = Error.class)
})

6、@ApiModel：用于描述实体类的信息，包括名称、描述等。（常用）

• value：DTO类的名称。
• description：DTO类的描述。

示例：@ApiModel(value = "用户DTO", description = "用户信息")

7、@ApiModelProperty：用于描述实体类中的属性信息。（常用）

• value：属性的描述。
• name：属性的名称。
• dataType：属性的数据类型。
• required：属性是否必须。
• example：属性的示例值。

示例：@ApiModelProperty(value = "用户ID", name = "userId", dataType = "int", required = true, example = "1")

8、@ApiIgnore 用于忽略某个API接口或API接口方法，不会在Swagger UI中显示。它可以用于在代码中标记一些不需要展示在Swagger UI中的接口或方法，避免Swagger UI中出现过多的无用接口和方法。

示例：

@ApiIgnore
public void someMethod() {
    // some code here
}

9、@ApiImplicitParam：用于描述API接口中的参数信息，与@ApiParam相似，但是可以用于描述多个参数。

• name：参数名称。
• value：参数的描述。
• required：参数是否必须。
• dataType：参数的数据类型。
• paramType：参数的类型，如path、query、body等。

示例：@ApiImplicitParams({
    @ApiImplicitParam(name = \\"userId\\", value = \\"用户ID\\", required = true, dataType = \\"int\\", paramType = \\"path\\"),
    @ApiImplicitParam(name = \\"userName\\", value = \\"用户名\\", required = true, dataType = \\"string\\", paramType = \\"query\\")
})

10、@ApiImplicitParams：用于描述API接口中的多个参数信息，与@ApiImplicitParam相似。
value：@ApiImplicitParam注解数组。

示例：

@ApiImplicitParams({
    @ApiImplicitParam(name = \\"userId\\", value = \\"用户ID\\", required = true, dataType = \\"int\\", paramType = \\"path\\"),
    @ApiImplicitParam(name = \\"userName\\", value = \\"用户名\\", required = true, dataType = \\"string\\", paramType = \\"query\\")
})

11、@ApiError：用于描述API接口方法的错误信息。

• code：错误状态码。
• reason：错误原因。

示例：@ApiError(code = 400, reason = \\"请求参数错误\\")

12、@ApiErrors：用于描述API接口方法的多个错误信息。

• value：@ApiError注解数组。

示例：

@ApiErrors(value = {
    @ApiError(code = 400, reason = \\"请求参数错误\\"),
    @ApiError(code = 500, reason = \\"服务器内部错误\\")
})

13、@ApiOperationSupport：用于描述API接口方法的其他信息，如文档、作者等。

• author：API接口方法的作者。
• since：API接口方法的版本号。
• tags：API接口方法的标签。

示例：@ApiOperationSupport(author = \\"John Doe\\", since = \\"1.0\\", tags = {\\"用户管理\\"})文章来源地址https://www.toymoban.com/news/detail-796658.html

到了这里，关于swagger ui 配置整合的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！