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

    @Bean
    public 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());
    }

    @Bean
    public 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());
    }

    @Bean
    public 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都无效。


分组

该文章参考多方文档