Swagger 使用Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web

SprintBoot 集成

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

接口的文档在线自动生成。
功能测试。

pom 引入

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

添加配置类 SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的方法，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，生成接口文档
                //.apis(RequestHandlerSelectors.basePackage("io.seu.modules.job.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("校管家管理系统")
                .description("校管家-api文档")
                .termsOfServiceUrl("https://localhost:8080/")
                .version("1.0.1")
                .build();
    }

}

常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

@Api：用在类上，描述Controller的作用

@Api：用在请求的类上，表示对类的说明
    tags="API分组标签。具有相同标签的API将会被归并在一组内展示。"
    value="如果tags没有定义，value将作为Api的tags使用"
    description="描述"
    
@Api(tags = {"TagController","Tag"},description = "标签控制器")

@ApiOperation：用在方法上，或者说接口

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="简单说明,展示在接口列表"
    notes="详细说明,展示在接口的详情页"
    tags="接口的标签，相同标签的接口会在一个标签页下展示"
    httpMethod="HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH""
    code="默认值200"

@ApiOperation(value = "热门标签",notes = "所有热门标签",tags = "Tag",httpMethod = "GET",response = R.class)

@ApiImplicitParams 和 @ApiImplicitParam 用在方法上

@ApiImplicitParams：
    @ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解

@ApiImplicitParam，请求参数属性配置：
    name：参数名称
    value：参数说明
    required：是否必须
    dataType：参数类型，默认String
    defaultValue：参数的默认值
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）

@ApiParam 用在参数上

@ApiResponses 和 @ApiResponse 用在方法上，表示响应

@ApiResponses
    @ApiResponse容器，可以包含多个@ApiResponse注解

@ApiResponse，返回结果属性配置：
        code：返回结果的编码。
        message：返回结果的说明。
        response：返回结果对应的类。

@ApiModel 用在实体类上 @ApiModelProperty 用在类属性上

@ApiModel是对整个类的属性的配置：
    value：类的说明
    description：详细描述
    
@ApiModelProperty是对具体每个字段的属性配置：
    name：字段名称
    value：字段的说明
    required：是否必须
    example：示例值
    hidden：是否显示