SpringBoot 集成Swagger
1.maven 配置
io.springfox
springfox-swagger2
2.5.0
org.springframework
spring-context
io.springfox
springfox-swagger-ui
2.5.0
2. SwaggerConfig
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
/**
如果项目配置tomcat访问路径，例如qdp-wain-web这样，需要配置下面的pathProvider方法，
未配置访问路径，则忽略pathProvider方法和HOST配置
**/
@Value("${spring.swagger.host}")
private String Host;
@Bean
public Docket swaggerSpringMvcPlugin(ServletContext servletContext) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//生成文档的api对象定义
.select()
.apis(RequestHandlerSelectors.basePackage("com.jimingqiang.study"))//扫描生成文档的包路径
//.paths(PathSelectors.ant("/*Api/*"))//生成文档的类访问路径，就是controller类里@RequestMapping("orderApi")
.paths(PathSelectors.any())
.build();
//.host(Host);//配置swagger前缀
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("JMQ-WEB构建restful接口api")//文档标题
.description("此API提供接口调用")//文档说明
.version("2.0").build();//版本号
}
}
-
SwaggerConfig必须与启动类同级，否则后台报错：
No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'
1539054671(1).jpg
3. swagger-ui.html的映射
代码如下：
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
- 如果不配置上述代码，我们在访问http://localhost:8080/swagger-ui.html时，会显示如下
-
后台错误：
No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'
4.注解
@Api：
作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。
参数：
- tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。
- description：可描述描述该类作用。
@RestController
@RequestMapping("/swaggerApi")
@Api(value = "SwaggerValue", tags={"SwaggerController"},description = "swagger应用", produces = MediaType.APPLICATION_JSON_VALUE)
public class SwaggerController {
@ApiOperation
用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
@RequestMapping(value="/test", method= RequestMethod.GET)
@ApiOperation(value="获取swagger信息",httpMethod = "GET",notes="注意问题点",produces = MediaType.APPLICATION_JSON_VALUE)
public String swaggerTest(@ApiParam(name="id",value="用户id",required=true) Long id){
return "swagger"+id;
}
@ApiParam
用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填
public String swaggerTest(@ApiParam(name="id",value="用户id",required=true) Long id){
return "swagger"+id;
}
@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@RequestMapping(value="/apiModeltest", method= RequestMethod.GET)
@ApiOperation(value="获取ApiModel信息",httpMethod = "GET",notes="ApiModel注意问题点",produces = MediaType.APPLICATION_JSON_VALUE)
public String swaggerTest1(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user ){
return user.toString();
}
@Data
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable {
@ApiModelProperty(value="用户名",name="username",required = true,example="xingguo")
private String name;
@ApiModelProperty(value="用户年龄",name="age",required = true,example="24")
private int age;
}
@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例
@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例
@ApiImplicitParam() 用于方法 表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数名
value–参数说明
dataType–参数的数据类型
example–举例说明
required-参数是否必填
paramType–查询参数类型,这里有几种形式
注意：当我发POST请求的时候，当时接受的整个参数，不论我用body还是query，后台都会报Body Missing错误。这个参数和SpringMvc中的@RequestBody冲突，索性我就去掉了paramType，对接口测试并没有影响。
@RequestMapping(value="/apiImplicitParamsTest", method= RequestMethod.GET)
@ApiOperation(value="获取apiImplicitParams信息",httpMethod = "GET",notes="apiImplicitParams注意问题点",produces = MediaType.APPLICATION_JSON_VALUE)
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用户名字", required = true, dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "id", value = "用户id", required = false, dataType = "long", paramType = "query")})
public String apiImplicitParamsTest(Long id,String name ){
return name;
}
ApiImplicitParam 与 ApiParam 的区别
ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments.
- 对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
- 在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
- ApiParam只需要较少的属性，与swagger ui配合更好。
彩蛋
微服务学习二：springboot与swagger2的集成
SpringBoot集成Swagger2中遇到的问题
Swagger-Core Annotations
swagger2的常用注解，传递参数的注意使用方法](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#api)