版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/u012946310/article/details/82353202
springboot与swagger的集成:
1,引入 jar 包:
<!-- 整合swagger,方便接口查看 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
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<Parameter> buildHeaderParam() {
// demo:设置在请求头里面公共参数token
List<Parameter> 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 隐藏该字段
controller 类编写好之后通过访问:
http://localhost:8080/swagger-ui.html
查看到 swagger 展示界面了
效果展示:
get 请求点击 Model 可以查看返回的各个字段
@ApiParam(hidden = true) 注解对于返回的 model 不会隐藏。
swagger 里面的 token 字段即为上面 MySwagger2Config 类里面的 buildHeaderParam 方法里面设置的字段,该字段会在提交时添加到请求头参数中,可以通过该字段验证用户是否有效性。
到这里 springboot 整合 swagger 就算完成了,如果有问题或者错误,可以给我留言。