springboot 整合 swagger

#springboot与swagger的集成：


1，引入 jar 包：

    io.springfox
    springfox-swagger2
    2.7.0


    io.springfox
    springfox-swagger-ui
    2.7.0

2，swagger的配置类编写：

package springboot_druid_demo.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2 // 开启swagger
public class MySwagger2Config extends WebMvcConfigurerAdapter {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                // 扫描指定包中的swagger注解
                .apis(RequestHandlerSelectors.basePackage("springboot_druid_demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
                .globalOperationParameters(buildHeaderParam());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("基础平台 RESTful APIs")
                .description("基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。")
                .version("1.0.0")
                .build();
    }

    /**
     * 设置在swagger里面的公共参数
     * 设置公共的参数。
     * 如：设置在请求头里面的token,userId等
     *
     * @return
     */
    private List buildHeaderParam() {

        // demo：设置在请求头里面公共参数token

        List pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());

        return pars;
    }

    @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/");

    }
}

上面代码中 .apis(RequestHandlerSelectors.basePackage 设置的 controller 包名称为自己的 controller 包名。
buildHeaderParam 方法里面是在 header 头里面设置的参数，如果不需要可以注释。

3，实际应用：
完善上面步骤后，我们就可以在 controller 类上使用 swagger 注解了，常用注解如下：

@Api(description = "用户controller") // 注解：应用在具体的 controller 上面
@ApiOperation("添加用户") // 注解：应用在 controller 里面的方法上
@ApiModelProperty("用户id") // 注解：应用在 model 字段上面
@ApiParam(hidden = true) // 注解：应用在 model 字段上面，表示对 swagger 隐藏该字段
@Accessors(chain = true) // 支持链式方法的调用

controller 类编写好之后通过访问：
http://localhost:8080/swagger-ui.html
查看到 swagger 展示界面了
效果展示：

get 请求点击 Model 可以查看返回的各个字段

@ApiParam(hidden = true) 注解对于返回的 model 不会隐藏。
swagger 里面的 token 字段即为上面 MySwagger2Config 类里面的 buildHeaderParam 方法里面设置的字段，该字段会在提交时添加到请求头参数中，可以通过该字段验证用户是否有效性。
到这里 springboot 整合 swagger 就算完成了，如果有问题或者错误，可以给我留言。
#如果生产环境需要关闭 swagger 文档，参考：https://blog.csdn.net/u012946310/article/details/82379429