Spring Boot集成 Swagger2 注解详解 paramType参数解析

---

前言

本次课题比较简单，由于处于项目初期，架构不成熟，有机会触及部分插件的的集成。为了更好地了解，并更好地应用这个插件，所以特写一篇相关笔记。

什么是Swagger

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
简单说
使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了。提供 Web 页面在线测试 API：参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
再细分一些

• Swagger 是一种规范。
• springfox-swagger2 是基于 Spring 生态系统的该规范的实现。
• springfox-swagger-ui 是对 swagger-ui 的封装，使其可以使用 Spring 的服务。

Spring Boot 项目引入Swagger2

pom.xml

 <!--swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

config.Swagger2.java
配置类
这个地方要注意termsOfServiceUrl和description必须有重复部分，且正好是url，这样在UI界面上才能看到链接。

/**
 * @author: T_Antry
 * @date: 2021/12/13 17:24
 * @description:
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.*.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact();
        return new ApiInfoBuilder()
                .title("T-Antry-日志服务接口")//接口管理文档首页显示
                .description("T_Antry博客：https://blog.csdn.net/qq_39150049/")//API的描述
                .termsOfServiceUrl("https://blog.csdn.net/qq_39150049/")//网站url等
                .contact("T_Antry")
                .version("1.0")
                .build();
    }

}

Controller.java

/**
 * @author: T_Antry
 * @date: 2021/12/14 17:29
 * @description:
 */
@RestController
@RequestMapping("/log/selectitem")
@Api(tags	= "下拉框选项相关接口",	value = "提供下拉框选项相关API")
public class SelectItemController {
    /**
     * logger
     */
    private static final Logger logger = LoggerFactory.getLogger(SelectItemController.class);
    @Autowired
    private SelectItemService selectItemService;
    @GetMapping("/getList")
    @ApiOperation(value="获取下拉框选项", notes="根据slectCode获取下拉框选项")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "selectCode", value = "selectCode",  paramType = "query", required = true, dataType =  "String")
    })
    public SelectItemResponse getItemList(  SelectItemDto dto){
        SelectItemResponse response = new SelectItemResponse();
        try {
            List<SelectItemVo> voList = *****
            response.setVoList(voList);
        }catch (LogBaseException e){
            ControllerUtil.doExceptionWork(logger,response,e);
        }catch (Exception e){
            ControllerUtil.doExceptionWork(logger,response, CodeMsgEnum.SELECT_ITEM_QUERT,e);
        }
        return response;
    }
}

使用

http://项目实际地址/swagger-ui.html

注解详解

@Api：用在类上，说明该类的作用。

• tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。
• description：可描述描述该类作用。

@ApiOperation：注解来给API增加方法说明。

• value 接口说明
• httpMethod 接口请求方式
• response 接口返回参数类型
• notes 接口发布说明

@ApiImplicitParams : 用在方法上包含一组参数说明。
可以包含一个或多个@ApiImplicitParam

@ApiImplicitParam：用来注解来给方法入参增加说明。

• name ：参数名。
• value ： 参数的具体意义，作用。
• required ： 参数是否必填。
• dataType ：参数的数据类型。
• paramType ：查询参数类型，这里有几种形式：

类型	作用
path	以地址的形式提交数据
query	直接跟参数完成自动映射赋值
body	以流的形式提交 仅支持POST
header	参数在request headers 里边提交
form	以form表单的形式提交 仅支持POST

@ApiResponses：用于表示一组响应
可以包含一个或多个@ApiResponses

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
用于类 ；表示对类进行说明，用于参数用实体类接收

• value–表示对象名
• description–描述

@ApiModelProperty：描述一个model的属性
用于方法，字段 ，表示对model属性的说明或者数据操作更改

• value:字段说明
• name:重写属性名字
• dataType:重写属性类型
• required:是否必填
• example:举例说明
• hidden:隐藏

@Data
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{ 
@ApiModelProperty(value="用户名",name="username",example="antry")
}

@ApiOperation("更改用户信息")
@PostMapping("/updateUser")
public int updateUser(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
	int num = userService.updateUserInfo(user);
	return num;
}