31.swagger生成在线接口文档

为什么要学习 swagger？？

强调前后分离项目

前端工程师负责美化页面，也就是写咱们的 vue 代码部分

后端工程师负责抛写接口，为前端提供数据支持

他们各司其职，但一个完整的项目，势必会涉及到前后端交互，如果前端也是你写，后端也是你写，那确实不需要什么 swagger 接口文档，但如果是分工合作的话，前端工程师调用你写的后端接口的时候，传什么参数，传几个参数，必须清楚才行，不然直接调用失败啊，还有调用完后端的接口响应回来的数据也得告诉清楚才能正常展示，这个时候如果有一个在线的接口文档就非常重要了。

springboot2.x 整合swagger流程

1.加依赖

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

2.Application.properties 中添加如下配置：

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

这个配置的作用是将 SpringBoot 路径匹配模式修改为 AntPathMatcher。Spring Boot 2.6.0 开始使用基于 PathPatternParser 的路径匹配，而 Springfox 版本一直没有更新还是使用 的 AntPathMatcher，如果不这样配置，将会抛出以下异常：

3.创建实体类 User

@Data
@AllArgsConstructor
@ApiModel(value = "用户User类",description = "描述用户User信息")
public class UserInfo {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "密码")
    private String password;
}

4.创建配置类 SwaggerConfig 启用 Swagger

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket desertsApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller"))//按包扫描,
                .paths(PathSelectors.any())
                .build()
                .groupName("jf3q")
                .enable(true);
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("用户管理系统说明API文档")//标题
                .description("用户管理系统说明API文档")//描述
                .contact(new Contact("jfit", "https://www.jf3q.com", "12345@qq.com"))//作者信息
//                .termsOfServiceUrl("https://www.sike.com")
                .version("1.0")//版本号
                .build();
    }
}

5.controller

@RestController
@RequestMapping("/user")
@Api(tags = "User操作接口")
public class UserInfoController {

    @Autowired
    UserInfoService userInfoService;
    @GetMapping("/{id}")
    @ApiOperation(value = "根据id查找用户对象", notes = "根据id查找用户对象")
    public ResultVo<UserInfo> getUser(@ApiParam(value = "用户ID", example = "1", required = true)@PathVariable Integer id){

        UserInfo userInfo=  userInfoService.getUser(id);
        return ResultVo.success("",userInfo);
    }

    @GetMapping
   
    public ResultVo<List<UserInfo>> getList(){
        List<UserInfo> list=userInfoService.getList();
        return ResultVo.success("",list);
    }
}

@Data
@AllArgsConstructor
public class ResultVo<T> {

    public String code;
    public String mess;
    public T data;

    public static<T> ResultVo<T> success(String mess, T data){
        return new ResultVo<T>("200",mess,data);
    }

    public static<T> ResultVo error(String mess){
        return new ResultVo<T>("500",mess,null);
    }
}

6.访问接口文档页面

http://localhost:端口/swagger-ui/index.html

美化ui界面

Swagger 自带的 UI 界面不是很好看，可以使用流行的第三方 swagger-bootstrap-ui 进行 美化，添加如下依赖，重新启动，访问地址：http://localhost:端口/doc.html

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

生产环境关闭swagger

一般 Swagger 只在开发和测试环境中使用，不带到生产环境中去。可以通过修改配置类 SwaggerConfig 里面的代码 enable(true)为 enable(false)来快速关闭 Swagger。更好的办法是自动识别是生成环境还是开发或测试环境，自动关闭或开启

@Bean
public Docket desertsApi(Environment environment){

//开发环境和测试环境
Profiles profiles=Profiles.of("dev","test");
//判断是否处在自己设定的环境当中
boolean swaggerEnabled = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller"))//按包扫描,
.paths(PathSelectors.any())
.build()
.groupName("jf3q")
.enable(swaggerEnabled);
}

拦截器放行 swagger

swagger 相关的页面不需要检验 token

  // swagger不需要检验token
                .excludePathPatterns(
                        "/swagger-ui/**",
                        "/swagger-ui.html/**",
                        "/v2/**",
                        "/webjars/**",
                        "/swagger-resources/**",
                        "/v3/api-docs/**",
                        "/v2/api-docs/**",
                        "/doc.html/**"
                )