Swagger 开发文档

----- Swagger -----

Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式文档，客户端 SDK 的⾃ 动生成等功能。

Swagger 的目标是为 REST API 定义一个标准的、与语⾔言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过 Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。

Swagger（丝袜哥）是世界上最流行的 API 表达工具。

Swagger 基础创建

Swagger 依赖

<!--Swagger 依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--Swagger Ui 前端页面-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

SwaggerConfig 配置类

在 SwaggerConfig 的类上添加两个注解：

注解	说明
@Configuration	启动时加载此类
@EnableSwagger2	表示此项目启用 Swagger API 文档功能

package com.apai.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   

    @Bean
    public Docket api() {
   
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // 此处自行修改为自己的 Controller 包路径。
            .apis(RequestHandlerSelectors.basePackage("com.apai.controller"))
            .paths(PathSelectors.any())
            .build();
    }
    private ApiInfo apiInfo() {
   
        return new ApiInfoBuilder()
            .title("阿派 项目接口文挡")
            .description("XXX Project Swagger2 UserService Interface")
            .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
            .version("1.0")
            .build();
    }

}

注意: 过滤 | 拦截

如果，你的项目中配置了拦截器，那么拦截器会拦截你的 /swagger-ui.html 请求，从而导致你看不到 swagger 页面。

这种情况下，你需要在你的拦截器的配置中，将 swagger 请求排除在外：

@Configuration
@EnableWebMvc
@ComponentScan("xxx.yyy.zzz.web.controller")
public class SpringWebConfig implements WebMvcConfigurer {
   
    // 暂未验证
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
   
        registry.addInterceptor(new MyInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns(
                    "/swagger-ui.html", 
                    "/swagger/**", 
                    "/swagger-resources/**"
                ).order(1);
    }
}

Swagger 常用注解

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等，常用注解内容如下：

注解	作用	备注
@Api(tags=“”)	用在请求的类上，表示对类的说明	tags属性：说明该类的作用，可以在UI界面上看到的注解
@ApiOperation	用在请求的方法上，说明方法的用途	value属性: 说明方法的用途、作用，response =“接口返回参数类型”，httpMethod = “接口请求方式”，produces=“请求头输出类型”
@ApiImplicitParams	用在请求的方法上，表示一组参数说明	多个@ApiImplicitParam组合
@ApiImplicitParam	指某个请求参数的各个方面	属性：1.name参数名称 2.value参数说明 3.required参数是否必须 4.allowMultiple=true 表示是数组格式的参数 5.paramType和dataType 如下案例说明，6.example表示参数的默认值
@ApiResponses	用在请求的方法上，表示一组响应	多个@ApiResponse组合
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息	code：数字，例如400，message：信息，例如"请求参数没填好"，response：抛出异常的类
@ApiModel(value = “理财实体类”)	用在实体类上	实体类相关说明
@ApiModelProperty	用在属性上，描述响应类的属性

请求参数详解

@ApiImplicitParams

• 用在请求的方法上，表示一组参数说明

• 多个@ApiImplicitParam组合

@ApiImplicitParams(value = {
   
    @ApiImplicitParam(),
    @ApiImplicitParam()
})
@ApiOperation("查询方法")
@PostMapping("/select")  //或者用getMapping("/select")
public Object select(String name,Integer id){
   
    return name + id;
}

@ApiImplicitParam

指某个请求参数的各个方面

属性：

• name | 参数名称
• value | 参数说明
• required | 参数是否必须
• allowMultiple=true | 表示是数组格式的参数
• paramType | 如下案例说明，
• dataType | 参数类型 实体类则写全路径
• example | 表示参数的默认值 int类型必须设置默认值

请求 paramType 属性详解

query

普通参数拼接，多个基本类型传参

@ApiImplicitParams(value = {
   
    @ApiImplicitParam(name = "name", value = "用户名", paramType = "query", dataType = "string", example ="xingguo"),
    @ApiImplicitParam(name = "id", value = "id", dataType = "int", example = "23", paramType = "query")
})
@ApiOperation("查询方法")
@GetMapping("/select")
public Object select(String name,Integer id){
   
    return name + id;
}

path

用于restful 风格的请求，且请求参数的获取：@PathVariable 注解接收

@ApiOperation(value = "获取用户信息", produces = "application/json")
@ApiImplicitParams({
   
    @ApiImplicitParam(name = "id", value = "用户Id", required = true, example = "23", dataType = "int", paramType = "path")
})
@GetMapping(value = "/get/{id}")
public Integer getUser(@PathVariable Integer id) {
   
    return id;
}

body（对象类型）

body：放在请求体，请求参数的获取：@RequestBody(代码中接收注解)，仅支持post

@ApiOperation(value = "获取用户")
@ApiImplicitParams({
   
    @ApiImplicitParam(name="financing",value = "用户对象",dataType = "com.woniu.entity.financing", paramType = "body"),
})
@PostMapping(value = "/getuser2")
public ResponseResult<String> getUser2(@RequestBody Financing financing){
   
    System.out.println(financing.toString());
    return new ResponseResult<String>(202,"成功了");
}

header

header 用来接收请求头参数，@RequestHeader(代码中接收注解）

@ApiOperation(value = "toke 请求头")
@ApiImplicitParams({
   
    @ApiImplicitParam