SpringBoot项目集成Swagger

1、 导包

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

2、常用配置

@Configuration
@EnableSwagger2
public class SwaggerConfig implements InitializingBean {
    @Autowired
    private Environment environment;

    private Boolean enable;

    @Bean
    public Docket userDocket() {
        return basicDocket(
                "用户",
                "用户接口文档",
                "用户接口文档描述",
                "/user/**");
    }

    @Bean
    public Docket productDocket() {
        return basicDocket(
                "产品",
                "产品接口文档",
                "产品接口文档描述",
                "/product/**");
    }

    /**
     * 封装了Docket的一些基本配置，创建多个Docket到Spring容器就可以实现分组
     */
    private Docket basicDocket(String groupName, String title, String description, String path) {

        // 创建全局参数
        Parameter token = new ParameterBuilder()
                .name("token")
                .description("全局参数令牌")
                // 参数数据类型
                .modelRef(new ModelRef("String"))
                // 参数类型（query/body/header）
                .parameterType("header")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用接口文档，可以根据项目环境做调整
                .enable(enable)
                // 添加全局参数token
                .globalOperationParameters(List.of(token))
                // 分组名称
                .groupName(groupName)
                // 接口文档描述信息
                .apiInfo(apiInfo(title, description))
                // 如果接口用到这些参数，生成的接口文档也会加入这些参数
                // 该方法让接口文档过滤掉指定类型的参数。
                .ignoredParameterTypes(
                        HttpServletRequest.class,
                        HttpServletResponse.class
                )
                // 获取ApiSelectorBuilder对象做一些过滤操作
                .select()
                // 只对指定的包生成接口文档
                // .apis(RequestHandlerSelectors.basePackage("com.cukiy.user.controller"))
                // 只对带有RestController注解的类生成接口文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                // 只对Path符合规则的方法生成接口文档,也可以把ant换成regex
                 .paths(PathSelectors.ant(path))
                // 过滤完成后转为Docket返回
                .build();

    }

    private ApiInfo apiInfo(String title, String description) {
        return new ApiInfoBuilder()
                // 接口文档标题
                .title(title)
                // 版本
                .version("1.0.0")
                // 描述
                .description(description)
                .build();
    }

    // 属性填充完成之后调用该方法,需要实现InitializingBean
    @Override
    public void afterPropertiesSet() throws Exception {
        // 配置了多套环境时，只在dev和test环境下启用接口文档
        enable = environment.acceptsProfiles(Profiles.of("dev","test"));
    }
}

3. 注解

Controller

@Api(tags = "用户")
public class UserController {

    @GetMapping("/queryById")
    @ApiOperation(value = "根据ID查询用户", notes = "ID不能为空")
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功")
    })
    public DataJsonVo<UserVo> queryById(
                    @ApiParam(value = "用户ID", required = true) 
                    @RequestParam
                    Long id) {
    }
}

VO

public class DataJsonVo<T> {
    @ApiModelProperty(value = "响应码")
    private Integer code;
    @ApiModelProperty(value = "响应信息")
    private String msg;
    @ApiModelProperty("响应数据")
    public T data;
}

public class UserVo {
    @ApiModelProperty("用户id")
    private Long id;
    @ApiModelProperty("昵称 ")
    private String nickname;
    @ApiModelProperty("年龄")
    private int age;
}

4. 备注

默认文档链接：项目地址/swagger-ui.html

如果使用了Shiro，需要开放以下接口

        filterChain.put("/swagger-ui.html", "anon");
        filterChain.put("/favicon.ico", "anon");
        filterChain.put("/webjars/**", "anon");
        filterChain.put("/swagger-resources/**", "anon");
        filterChain.put("/v2/**", "anon");

5.运行效果

swagger01.png