一.swagger是什么?
1.支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
2.提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。
二.swagger配置与使用
1.引入依赖
<!-- swagger start -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<!-- swagger end -->
2.加入配置类
@Configuration
@EnableSwagger2
@ConditionalOnProperty(
name = {"swagger.enable"},
havingValue = "true"
)
public class Swagger2Config {
@Value("${swagger.title}")
private String title;
@Value("${swagger.base.package}")
private String basePackage;
@Value("${swagger.description}")
private String description;
@Value("${swagger.url}")
private String url;
@Value("${swagger.contact.name}")
private String contactName;
@Value("${swagger.contact.url}")
private String contactUrl;
@Value("${swagger.contact.email}")
private String contactEmail;
@Value("${swagger.version}")
private String version;
public Swagger2Config() {
}
@Bean
public Docket createRestApi() {
return (new Docket(DocumentationType.SWAGGER_2)).apiInfo(this.apiInfo()).select().apis(RequestHandlerSelectors.basePackage(this.basePackage)).paths(PathSelectors.any()).build().globalOperationParameters(this.setHeaderToken());
}
private ApiInfo apiInfo() {
return (new ApiInfoBuilder()).title(this.title).description(this.description).termsOfServiceUrl(this.url).contact(new Contact(this.contactName, this.contactUrl, this.contactEmail)).version(this.version).build();
}
private List<Parameter> setHeaderToken() {
List<Parameter> pars = new ArrayList();
String testTokenValue = "";
ParameterBuilder tokenPar = new ParameterBuilder();
Parameter tokenParameter = tokenPar.name("token").description("Token Request Header").modelRef(new ModelRef("string")).parameterType("header").required(false).defaultValue(testTokenValue).build();
pars.add(tokenParameter);
return pars;
}
}
3.controller加入注解
@Slf4j
@RestController
@RequestMapping("/zntsSendInfo")
@Api(tags="推送内容信息表 API",description = "提供推送内容信息表相关的 Rest API")
public class ZntsSendInfoController extends BaseController {
/**
* 添加推送内容信息表
*/
@PostMapping("/add")
@ApiOperation(value = "添加ZntsSendInfo对象", notes = "添加推送内容信息表")
public ApiResult<Boolean> addZntsSendInfo(@Valid @RequestBody ZntsSendInfo zntsSendInfo) throws Exception {
boolean flag = zntsSendInfoServiceImpl.saveZntsSendInfo(zntsSendInfo);
//noinspection unchecked
return ApiResult.result(flag);
}
}
4.实体类加注解
@Data
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = true)
@ApiModel(value = "ZntsSendInfo对象", description = "推送内容信息表")
public class ZntsSendInfo extends BaseEntity {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主键",required =true)
@TableId(value = "id", type = IdType.ID_WORKER)
private Long id;
@ApiModelProperty(value = "目标类型;")
private String targetType;
@ApiModelProperty(value = "目标信息")
private String targetInfo;
@ApiModelProperty(value = "推送状态;")
private String sendStatus;
@ApiModelProperty(value = "发送时间")
private Date sendTime;
}
5.application.yml配置文件
# swagger配置
swagger:
enable: true
base:
package: com.sinosoft.springbootplus
contact:
email: zhangsan@168.com
name: 张三
url: ''
description: ''
title:
url: ''
version: 1.0
6.查看api问题、单元测试
使用 http://ip:端口号/doc.html。这个版本是是用了xiaoymin的swagger,它的页面是这样的
调试页面