SpringBoot整合swagger的基本使用

Swagger是一个接口文档工具，使得后端开发者在完成后端接口的同时即完成了接口文档的编写，规范的定义了接口的详细信息，提高效率的工具。

以下是我在 IDEA 中用 SpringBoot2.x 版本整合和使用 swagger2.9.x 版本的教程。

1.首先在maven central仓库中搜索springfox swagger, 选择想要导入项目的依赖版本, 我这里使用的是2.9.2版本

        <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.新建config包，编写swaggerConfig配置类

@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docketTest() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

此时已启动Swagger服务了，可以通过 http://localhost:8080/swagger-ui.html 检查是否能访问到swagger-ui.html页面。若报404错误的话，则属于SpringBoot将.html后缀的页面识别成了静态资源，我们需要配置静态资源映射才可以访问到。

@Configuration
public class WebConfig 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/");
    }
}

3.在swaggerConfig中对swagger-ui页面进行参数配置

    private ApiInfo apiInfo() {
        Contact contact = new Contact("ZYQ", "aaa.com", "709401953@qq.com");
        return new ApiInfo("Swagger学习接口文档",
                "这是学习Swagger时生成的文档信息",
                "v1.0",
                "http://localhost:8080",
                contact,
                "",
                "",
                new ArrayList<>());
    }

@Bean
public Docket docketApiInfo() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}

4.进行其他各类配置

@Bean
    public Docket docketUser() {
        //控制swagger在特定环境下展示
        Profiles profiles = Profiles.of("dev", "test");
        boolean isEnable = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                //true展示 false不展示
//                .enable(isEnable)
                //配置接口忽略参数 (request, response, session等参数是自动忽略的
                // 也就是说前端传值的参数才会被默认显示)
//                .ignoredParameterTypes(Integer.class, Long.class)
                .apiInfo(apiInfo())
                .groupName("用户")
                //选择展示在swagger-ui.html页面上的api
                .select()
                //通过包名扫描
//                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                //接口过滤 只需要hello路由下的接口
                .paths(PathSelectors.ant("/user/**"))
                //通过类上的注解扫描
//                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                //通过方法上的注解扫描
//                .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                .build();
    }

5.在接口方法上进行配置

@Api(tags = "测试接口")
@RestController
@RequestMapping("/test")
public class TestController {

    @ApiOperation("测试信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = "String", paramType = "header", defaultValue = "admin", example = "admin"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "String", paramType = "header", defaultValue = "123456", example = "123456")
    })
    @GetMapping
    public String getTest(String username, String password) {
        return "test";
    }

    @ApiOperation("测试类注释")
    @PostMapping
    public Test test(Test test) {
        return test;
    }

    @ApiOperation("删除")
    @DeleteMapping
    public Test delTest(@RequestBody Test test) {
        return test;
    }
}

6.0在实体类上进行配置

@ApiModel("测试类实体")
public class Test {
    //为防止空指针异常 对非String类型的数据进行example设置
    @ApiModelProperty(value = "用户id", example = "0")
    private Integer id;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty(value = "年龄", example = "0")
    private Integer age;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public Test(Integer id, String username, Integer age) {
        this.id = id;
        this.username = username;
        this.age = age;
    }

    @Override
    public String toString() {
        return "Test{" +
                "id=" + id +
                ", username='" + username + '\'' +
                ", age=" + age +
                '}';
    }
}