swagger 2.9.2

 

依赖:

        <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>

 

Swagger 2的配置类:

/**
 * Created by xc on 2019/9/19
 * Swagger2API文档的配置
 * 2022/07/01 增加注释
 * 2022/07/06 升级版本 2.6.1 -> 2.9.2
 */
@Configuration
@EnableSwagger2 // 开启Swagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        // 配置一个Docket
        return new Docket(DocumentationType.SWAGGER_2) // DocumentationType 即文档类型的选择我们需要根据集成的 Swagger 的版本来选择，这里选择 SWAGGER_2 表示使用的 Swagger 是2.X系列版本。
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xc.xcspringboot.controller")) //为当前包下controller生成API文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@Api注解的Controller生成API文档
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //为有@ApiOperation注解的方法生成API文档
                .paths(PathSelectors.any()) // 将项目中所有接口的请求路径都暴露给 Swagger 来生成 Swagger-UI 界面
                .build()
                .apiInfo(
                        new ApiInfoBuilder()
                                .title("API测试文档xc") // Swagger-UI 界面的大标题
                                .description("xcspringboot项目") //  Swagger-UI 界面的一些简单描述信息
                                .contact(new Contact("xc", "https://gitee.com/xxx", "xxx@xxx.com"))
                                .version("1.0") // 界面上所有接口的版本
                                .license("Apache2.0")
                                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                                .build()
                ); // 在apiInfo中构建文档的基本信息
    }

}

　　

示例接口:

@Slf4j
@Api(tags = "用户数据接口") // @Api注解用在类上，用来描述整个Controller信息
@RestController
public class SwaggerUserController {

    // @ApiOperation注解用在开发方法上，用来描述一个方法的基本信息，value是对方法作用的一个简短描述，notes则用来备注该方法的详细作用。
    @ApiOperation(value = "查询用户", notes = "根据id查询用户")
    /*
     * @ApiImplicitParam注解用在方法上，用来描述方法的参数，
     * paramType是指方法参数的类型，
     * 可选值有path（参数获取方式@PathVariable）、query（参数获取方式@RequestParam）、header（参数获取方式@RequestHeader）、body以及form；
     * name表示参数名称，和参数变量对应；
     * value是参数的描述信息；
     * required表示该字段是否必填；
     * defaultValue表示该字段的默认值。
     *
     * 注意，这里的required和defaultValue等字段只是文档上的约束描述，并不能真正约束接口，约束接口还需要在@RequestParam中添加相关属性。
     *
     * 如果方法有多个参数，可以将多个参数的@ApiImplicitParam注解放到@ApiImplicitParams中。
     */
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "/user/" + id;
    }

    /*
     * @ApiResponse注解是对响应结果的描述，
     * code表示响应码，
     * message表示相应的描述信息，
     * 若有多个@ApiResponse，则放在一个@ApiResponses中。
     */
    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功!"),
            @ApiResponse(code = 500, message = "删除失败!")})
    @ApiOperation(value = "删除用户", notes = "通过id删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "添加用户", notes = "添加- -个用户,传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "sang"),
            @ApiImplicitParam(paramType = "query", name = "address", value = "用户地址", required = true, defaultValue = "shenzhen")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String address) {
        return username + ":" + address;
    }

    // 使用@RequestBody注解来接收数据，此时可以通过@ApiModel注解和@ApiModelProperty注解配置User对象的描述信息。
    @ApiOperation(value = "修改用户", notes = "修改用户,传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user) {
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore // @ApiIgnore注解表示不对某个接口生成文档
    public void ingoreMethod() {
    }

}

　　

@ApiModel(value = "用户实体类", description = "用户信息描述类")
@Data
public class User {

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "用户地址")
    private String address;

}