Swagger保姆级教学
Swagger 简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
快速上手
1.新建一个springboot项目
2.导入maven依赖(swagger2和swagger UI)
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
3.启动项目，访问http://localhost:端口/swagger-ui.html
4.新建一个SwaggerConfig.java
package com.littlepage.config;
import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 配置swagger bean实例
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
/**
* 配置swagger信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfo("steve yu's API document",
"for quick start swagger", "1.0",
"https://www.cnblogs.com/littlepage/",
new Contact("steve yu", "https://www.cnblogs.com/littlepage/", "[email protected]"),
"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<>());
}
}
启动页面
5.配置扫描接口(修改Bean)
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).
apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.littlepage.controller")).build();
}6.在环境中进行配置（工程扫描接口开关）
@Bean
public Docket docket(Environment environment){
Profiles profiles=Profiles.of("dev","test");//假设有dev和test环境变量
boolean flag=environment.acceptsProfiles(profiles);
return new Docket(DocuemtatuionType.SWAGGER_2).enable(flag);//如果环境配置了，则生效，否则不生效
}7.API文档的分组。
new Docket().group(String s)
//这个String s可以规定分组8.单API样例(参考https://www.jianshu.com/p/349e130e40d5）
#####Controller代码
@Override
@ApiOperation(value = "post请求调用示例", notes = "invokePost说明", httpMethod = "POST")
public FFResponseModel invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
log.info("/testPost is called. input=" + input.toString());
return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
}
#####接口请求入参对象
@Data
@ApiModel(value="演示类",description="请求参数类" )
public class DemoDto implements Serializable {
private static final long serialVersionUID = 1L;
@NotNull
@ApiModelProperty(value = "defaultStr",example="mockStrValue")
private String strDemo;
@NotNull
@ApiModelProperty(example="1234343523",required = true)
private Long longNum;
@NotNull
@ApiModelProperty(example="111111.111")
private Double doubleNum;
@NotNull
@ApiModelProperty(example="2018-12-04T13:46:56.711Z")
private Date date;
}
#####接口请求出参公共类
@ApiModel(value="基础返回类",description="基础返回类")
public class FFResponseModel implements Serializable {
private static final long serialVersionUID = -2215304260629038881L;
// 状态码
@ApiModelProperty(example="成功")
private String code;
// 业务提示语
@ApiModelProperty(example="000000")
private String msg;
// 数据对象
private T data;
...
}
#####接口请求出参实际数据对象
@Data
public class DemoOutputDto {
private String res;
@NotNull
@ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
private String outputStrDemo;
@NotNull
@ApiModelProperty(example="6666666",required = true)
private Long outputLongNum;
@NotNull
@ApiModelProperty(example="88888.888")
private Double outputDoubleNum;
@NotNull
@ApiModelProperty(example="2018-12-12T11:11:11.111Z")
private Date outputDate;
}