手把手带你上手swagger3

配置POM

只需要加一个依赖，并且要注意，swagger3在springboot2.5版本以上会出现问题

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

如果高于2.5版本会报错：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

解决方法是降低spring的版本到2.5.x以下，或者是降低swagger版本到3以下，或者是在SwaggerConfig注解上标注@EnableWebMvc

配置例子

配置SwaggerConfig

@Configuration
@EnableSwagger2
@Slf4j
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 文档基础配置
                .select()
                .paths(PathSelectors.regex("(?!/error.*).*"))  //加这行去除掉basic error controller接口
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx平台接口文档")
                .build();
    }

}

配置实体类

@ApiModel(value = "UsersDTO", description = "UsersDTO实体类")
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class UserDTO {

    @ApiModelProperty(value = "First name", example = "Jean")
    private String firstname;

    @ApiModelProperty(value = "Last name", example = "ab")
    private String lastname;

    @ApiModelProperty(value = "CardInfo")
    private CardInfo cardInfo;

}

可以看到这个类存在CardInfo嵌套类，对嵌套类的配置同上：

@ApiModel(value = "CardInfo", description = "CardInfo实体类")
@Data
public class CardInfo {

    @ApiModelProperty(value = "cardName", example = "card")
    String cardName;
}

注意：实体类的字段都需要有get方法，不然会失效，这里统一使用lombok的@Data解决

配置Controller类

@RestController
@Api(tags = "用户管理接口")
@RequestMapping("/users")
public class UsersController {

    @Autowired
    private UsersService usersService;

    @ApiOperation(value = "用户注册",notes = "传入用户信息进行注册")
    @PostMapping(value = "/register")
    public AjaxResult<Users> register(@RequestBody Users users) throws IOException {
        usersService.save(users);
        return AjaxResult.success(users);
    }

}

这里面的返回值AjaxResult需要定义好泛型，在返回值初定义类型

AjaxResult类

@ApiModel("API通用返回数据")
@Data
public class AjaxResult<T> {

    @ApiModelProperty(value = "状态码", example = "200")
    private final int code;

    @ApiModelProperty(value = "返回消息", example = "success")
    private final String message;

    @ApiModelProperty("数据对象")
    private final T data;

    public AjaxResult(int code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public int getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }

    public T getData() {
        return data;
    }

    public static <T> AjaxResult<T> success() {
        return new AjaxResult<>(ResultCodeEnum.SUCCESS.getCode(), ResultCodeEnum.SUCCESS.getMessage(), null);
    }

    public static <T> AjaxResult<T> success(String message) {
        return new AjaxResult<>(ResultCodeEnum.SUCCESS.getCode(), message, null);
    }

    public static <T> AjaxResult<T> success(T data) {
        return new AjaxResult<>(ResultCodeEnum.SUCCESS.getCode(), ResultCodeEnum.SUCCESS.getMessage(), data);
    }

    public static <T> AjaxResult<T> success(String message, T data) {
        return new AjaxResult<>(ResultCodeEnum.SUCCESS.getCode(), message, data);
    }

    public static <T> AjaxResult<T> failed() {
        return new AjaxResult<>(ResultCodeEnum.FAILED.getCode(), ResultCodeEnum.FAILED.getMessage(), null);
    }

    public static <T> AjaxResult<T> failed(String message) {
        return new AjaxResult<>(ResultCodeEnum.FAILED.getCode(), message, null);
    }

    public static <T> AjaxResult<T> failed(ResultCodeEnum resultCodeEnum) {
        return new AjaxResult<>(resultCodeEnum.getCode(), resultCodeEnum.getMessage(), null);
    }

    public static <T> AjaxResult<T> failed(String message, T data) {
        return new AjaxResult<>(ResultCodeEnum.FAILED.getCode(), message, data);
    }

    public static <T> AjaxResult<T> failed(ResultCodeEnum resultCodeEnum, T data) {
        return new AjaxResult<>(resultCodeEnum.getCode(), resultCodeEnum.getMessage(), data);
    }
}

效果

swagger有关的常用注解

@Api 注解：

@Api 注解用于描述整个 API，通常放在控制器类上，一般使用tags注解就可以

@Api(tags = "User API")
@RestController
@RequestMapping("/api/users")
public class UserController {
    // ...
}

@ApiOperation 注解：

@ApiOperation 注解用于描述具体的 API 操作，通常放在控制器方法上

@ApiOperation(
    value = "Get user by ID",
    notes = "Get user details by providing user ID"
)
@GetMapping("/{userId}")
public ResponseEntity<User> getUserById(@PathVariable Long userId) {
    // Implementation to get user by ID
}

@ApiParam 注解：

@ApiParam 注解用于描述方法参数，提供参数的名称、描述等信息。

@GetMapping("/{userId}")
public ResponseEntity<User> getUserById(
    @ApiParam(name = "userId", value = "ID of the user", required = true)
    @PathVariable Long userId) {
    // Implementation to get user by ID
}

@ApiResponse 和 @ApiResponses 注解：

这两个注解用于描述操作的响应信息，作用在方法上。

@ApiResponses({
    @ApiResponse(code = 200, message = "Successful operation", response = String.class),
    @ApiResponse(code = 404, message = "User not found", response = String.class),
})
@GetMapping("/{userId}")
public ResponseEntity<User> getUserById(@PathVariable Long userId) {
    // Implementation to get user by ID
}

@ApiModel 和 @ApiModelProperty 注解：

这两个注解用于描述数据模型，通常放在实体类上。其中，下述的example可以实现在swagger页面调接口的默认值，并且如果导入到如eolink这种api管理工具，这个默认值也会填充进去。
```
@ApiModel(description = "User information")
public class User {
    @ApiModelProperty(value = "User ID", example = "ab")
    private Long id;

    @ApiModelProperty(value = "User name", example = "cd")
    private String name;

    // Getters and setters
}
```
@ApiIgnore 注解：

@ApiIgnore 注解用于标记不想在 Swagger 文档中显示的类、方法。
```
@ApiIgnore
public class IgnoredController {
    // ...
}
```
上述的 IgnoredController 类及其所有方法将被忽略。

@ApiParamImplicit 注解：

@ApiParamImplicit 注解用于表示参数，需要被包含在注解@ApiImplicitParams之内。

@ApiImplicitParams({
    @ApiImplicitParam(name = "userId", value = "ID of the user", required = true, dataType = "long", paramType = "path"),
})
@GetMapping("/{userId}")
public ResponseEntity<User> getUserById(
    @PathVariable Long userId) {
    // Implementation to get user by ID
}