Swagger是一套用于RESTful API开发的工具,可以生成非常直观的接口文档用于前后端分离的接口交流。
SpringFox是一个扫描代码中的信息,生成API文档的工具。API文档的格式不止swagger的OpenAPI规范,还有RAML、jsonAPI等。
Springfox官方文档
引入最新版的Springfox依赖
<repositories>
<repository>
<id>jcenter-snapshotsid>
<name>jcentername>
<url>https://jcenter.bintray.com/url>
repository>
repositories>
<dependencies>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
dependency>
dependencies>
新建Swagger配置文件 SwaggerConfig(命名没有要求)
package com.usongon.starfire.bean.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @author usongon
* @date 2020/10/23
*/
@Configuration
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
.select()
//"com.usongon.starfire" 是扫描的包
.apis(RequestHandlerSelectors.basePackage("com.usongon.starfire"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo getApiInfo(){
return new ApiInfoBuilder()
//项目标题
.title("星火")
//项目描述
.description("星火项目接口文档")
//版本
.version("1.0.0")
//联系方式
.contact(new Contact("usongon", "usongon.com", "dehua@88.com"))
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//解决跨域问题
registry.addResourceHandler("/**").addResourceLocations("/");
}
}
在Controller文件中使用注解,示例代码如下:
package com.usongon.starfire.controller;
import com.usongon.starfire.service.IUserInfoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
/**
* @author usongon
* @date 2020/10/23
*/
@Api(value = "用户模块")
@RestController
@RequestMapping("/user")
public class UserInfoController {
@Resource
private IUserInfoService userInfoService;
@ApiOperation(value = "获取全部用户信息", notes = "暂时无须参数")
@PostMapping("/getAll")
public String getAllUserInfo(){
return userInfoService.list().toString();
}
}
常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用 该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
@ApiImplicitParam属性:
paramType 查询参数类型
path 以地址的形式提交数据
query 直接跟参数完成自动映射赋值
body 以流的形式提交 仅支持POST
header 参数在request headers 里边提交
form 以form表单的形式提交 仅支持POST
dataType 参数的数据类型 只作为标志说明,并没有实际验证 Long String
name 接收参数名
value 接收参数的意义描述
required 参数是否必填 true 必填 false 非必填
defaultValue 默认值
运行项目,访问http://host/context-path/swagger-ui/index.html
或者 http://host/context-path/swagger-ui/
如 localhost:8080/swagger-ui/index.html
注意,在Springfox3.0之前,访问地址为http://host/context-path/swagger-ui.html
如 localhost:8080/swagger-ui.html
在升级为Springfox3.0之后,访问地址发生了变化,这一点要注意。
在这里我们就能看见我们编写的api文档了,点击user-info-controller(根据controller文件的名字自动生成的),我们可以看见接口信息
我们可以点击之后看见详情
并可以点击 try it out来进行测试
在项目名下方有一个地址
复制这个地址,打开Postman,点击import
点击link,粘贴我们刚才复制的地址
点击Continue,再点击import就可以导入了,这时我们就可以在Collections中看到我们导入的接口信息了!
和
springfox-swagger-ui 依赖@EnableSwagger2
注释springfox-boot-starter
(参考上方教程第一步)@EnableWebMvc
注释,请添加此注释。Springfox官方文档