桂林网站设计制作企业展厅 设计 公司 平安

Swagger3常用配置注解

@ApiImplicitParams,@ApiImplicitParam：Swagger3对参数的描述。

参数名	参数值
name	参数名
value	参数的具体意义，作用。
required	参数是否必填。
dataType	参数的数据类型。
paramType	查询参数类型

paramType有如下几种形式：

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

@ApiResponses， @ApiResponse：Swagger3对响应信息的描述。

参数名	参数值
code	响应码：400
message	信息，例如：请求参数类型错误。
response	抛出异常的类。

Controller层

package com.xct.swagger_1.controller.one;import com.xct.swagger_1.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;/*** @author xct* @date 2023年03月01日 16:08*/
@Api("接口测试")
@RestController
@RequestMapping("novel")
public class Test1Controller {@ApiOperation("测试功能1")@GetMapping("hello")public String test(){return "HelloYc";}@PostMapping("search")@ApiImplicitParams({@ApiImplicitParam(name="name",value ="姓名",required=true,paramType="query"),@ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "Integer")})@ApiOperation("测试查询")public String search(String name,Integer age){return name+":"+age;}@ApiOperation("测试增加")@PostMapping("add")public String add(@RequestBody User user){return user.getName()+":"+user.getAge();}@GetMapping("user/{id}")@ApiOperation("根据id获取用户信息")@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "用户编号",required = true,paramType = "path")})@ApiResponses({@ApiResponse(code=500,message = "后端代码错误"),@ApiResponse(code=400,message = "请求参数类型错误"),@ApiResponse(code=404,message = "请求路径错误")})public User load(@PathVariable("id") Long id){return new User(id,"jack",32,1,"无");}
}

接口测试

API信息配置

SwaggerConfig配置文件

package com.xct.swagger_1.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
//@EnableSwagger2 //swagger3版本不需要使用这个注解，当然写上也无所谓~
public class SwaggerConfig {//配置Swagger的Docket bean@Beanpublic Docket createRestApi1() {return new Docket(DocumentationType.OAS_30)// 指定Swagger3.0版本.groupName("开发组001").select().apis(RequestHandlerSelectors.basePackage("com.xct.swagger_1.controller.one"))//扫描指定包下的api.build().apiInfo(createApiInfo());}@Beanpublic Docket createRestApi2() {return new Docket(DocumentationType.OAS_30)// 指定Swagger3.0版本.groupName("开发组002").select().apis(RequestHandlerSelectors.basePackage("com.xct.swagger_1.controller.two"))//扫描指定包下的api.build().apiInfo(createApiInfo());}@Beanpublic ApiInfo createApiInfo() {return new ApiInfoBuilder().title("yc&xct管理平台").description("yc&xct管理平台 API接口文档").license("南京信息技术有限公司").licenseUrl("").version("1.0").build();}
}

Swagger3 Docket开关，过滤，分组

开关：调用enable方法。
开：


关：

过滤：调用select方法；通过apis方法，basePackage可以根据包路径来生成特定类的API，any方法是默认所有都有效，none方法都无效。withClassAnnotation根据类注解，withMethodAnntation是根据方法注解，一般我们用的是basePackage方法。

控制器1：

package com.xct.swagger_1.controller.one;import com.xct.swagger_1.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;/*** @author xct* @date 2023年03月01日 16:08*/
@Api("接口测试")
@RestController
@RequestMapping("novel")
public class Test1Controller {@ApiOperation("测试功能1")@GetMapping("hello")public String test(){return "HelloYc";}@PostMapping("search")@ApiImplicitParams({@ApiImplicitParam(name="name",value ="姓名",required=true,paramType="query"),@ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "Integer")})@ApiOperation("测试查询")public String search(String name,Integer age){return name+":"+age;}@ApiOperation("测试增加")@PostMapping("add")public String add(@RequestBody User user){return user.getName()+":"+user.getAge();}@GetMapping("user/{id}")@ApiOperation("根据id获取用户信息")@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "用户编号",required = true,paramType = "path")})@ApiResponses({@ApiResponse(code=500,message = "后端代码错误"),@ApiResponse(code=400,message = "请求参数类型错误"),@ApiResponse(code=404,message = "请求路径错误")})public User load(@PathVariable("id") Long id){return new User(id,"jack",32,1,"无");}
}

控制器2：

package com.xct.swagger_1.controller.two;import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;/*** @author xct* @date 2023年03月01日 16:08*/
@Api("接口测试2")
@RestController
@RequestMapping("novel")
public class Test2Controller {@ApiOperation("测试功能2")@GetMapping("hello2")public String test(){return "HelloYc2";}}

测试：
basePackage:指定包路径下的api

any:任何api都有效。


none:任何api都无效。


分组

该文章参考多方文档