04| SwaggerConfiguration配置类

· · · ·

依赖包

```xml

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

在公共模块中配置： `\nla\common\config\SwaggerConfiguration.java`

#### 配置用户端服务接口文档

```java
/**
 * Swagger配置
 **/
@Data
@Component
@EnableOpenApi
public class SwaggerConfiguration {
    /**
     * 对用户服务端的接口文档
     */
    @Bean
    public Docket userApiDoc() {
        return new Docket(DocumentationType.OAS_30) // 版本3.0
                .groupName("用户端接口文档")
                .pathMapping("/")
                //定义是否开启Swagger，false是关闭，可以通过变量去控制，线上关闭
                .enable(true)
                //配置文档的元信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.nla"))
                //正则匹配请求路径，并分配到当前项目组
                .paths(PathSelectors.ant("/user/**"))
                .build()
                // 新版SwaggerUI3.0
                .globalRequestParameters(globalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }
    /**
     * 接口基本信息配置
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("电商平台")
                .description("微服务接口文档")
                .contact(new Contact("yuan", "http://localhost", "yuanjs625@163.com"))
                .version("v1.0")
                .build();
    }
}   
```

访问地址：`/swagger-ui/index.html`

请求需要自定义http头，比如登录token令牌

```java
  /**
     * 配置全局通用参数
     */
    private List<RequestParameter> globalRequestParameters() {
        return List.of(new RequestParameterBuilder()
                .name("token")
                .description("登录令牌")
                .in(ParameterType.HEADER)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
    }

/**
     * 生成通用的响应信息
     */
    private List<Response> getGlobalResponseMessage() {
        return List.of(new ResponseBuilder()
                .code("4xx")
                .description("请求错误，根据code和msg检查")
                .build());
    }
```

请求地址：`/swagger-ui/index.html`

配置请求参数和前端控制器

```java
@Api(tags = "文件相关控制器")
@RestController
@RequestMapping("/user/file/v1")
@Slf4j
public class FileController {
    @Resource
    private FileService fileService;

@ApiOperation("用户头像上传")
    @PostMapping(value = "/uploadFile")
    public JsonData uploadHeaderImg(@ApiParam(value = "文件上传", required = true) @RequestPart("file") MultipartFile file) {
        return JsonData.buildSuccess(fileService.uploadUserHeadImg(file));
    }
}
```

- @Api(tags = "文件相关控制器")  定义控制器名称
- @RequestMapping("/user/file/v1")       规则：**定义的接口文档前缀 + 控制器分类+ 版本**
- @ApiOperation("用户头像上传")   定义接口名称
- @ApiParam(value = "文件上传", required = true)     **GET请求参数/POST请求对象**名称，是否是必传参数

```java
@Data
@ApiModel(value = "【Request】登录对象", description = "用户登录请求对象")
public class UserLoginRequest {
    @ApiModelProperty(value = "邮箱", example = "794666918@qq.com")
    private String mail;
    @ApiModelProperty(value = "密码", example = "123456")
    private String pwd;
}
```

- @ApiModel(value = "登录对象", description = "用户登录请求对象")   对象名称及说明
- @ApiModelProperty(value = "密码", example = "123456")    请求参数名称及举例参数值

响应对象

```java
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "【Response】模型选择对象", description = "模型选择的数据结构")
public class KeyValueVO {
    @ApiModelProperty(value = "模型ID", required = true)
    private Long key;
    @ApiModelProperty(value = "模型名称", required = true)
    private String value;
}
```

#### 注意

1. 如果配置是是https域名访问，在nginx做了url代理配置（eg:  映射关系： https://api.shop.com/web/user/**  => http://127.0.0.1:8080/user/**) ，访问地址：https://api.shop.com/web/swagger-ui/index.html
2. 要开启HTTPS且点击(https://api.shop.com/web/v2/api-docs)可访问
3. 控制正式环境关闭Swagger

修改配置

```java
@Resource
private Environment env;
@Bean
public Docket userApiDoc() {
    String[] pas = env.getActiveProfiles();
    return new Docket(DocumentationType.SWAGGER_2) // 版本2.0
            .host("api.shop.com") // 域名设置
            .protocols(Collections.singleton("https")) // 开启HTTPS
            // .groupName("用户端接口文档") 不能定义，否则不可访问
            .pathMapping("/web") // nginx代理的前缀
            //定义是否开启Swagger，false是关闭，prod 正式环境关闭
            .enable(pas.length <= 0 || !"prod".equals(pas[0]))
            //配置文档的元信息
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("cn.nla"))
            //正则匹配请求路径，并分配到当前项目组
            .paths(PathSelectors.ant("/user/**"))
            .build()
            .globalRequestParameters(globalRequestParameters())
            .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
            .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
}
```

04| SwaggerConfiguration配置类

编码规范参考文档

关于Vue和Python相关的资料文档

Git Fork后的仓库内容和原仓库保持一致

JDK 源码解析 —— 调试环境搭建（二）进阶

JDK 源码解析 —— 集合（一）数组 ArrayList

Dubbo 源码分析 —— 调试环境搭建