Swagger好处啥的略过，因为需要用，所以就用了。
废话不多说，直接上步骤
Swagger开发（基于maven工程，swagger2包）
关于swagger的相关注解，可以参见 https://blog.csdn.net/xiaojin21cen/article/details/78654652
1、依赖添加
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger-ui为项目提供api展示及测试的界面 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、添加配置类，新建一个类SwaggerConfig，代码如下
@Configuration //声明该类为配置类
@EnableSwagger2 //声明启动Swagger2
@EnableWebMvc //声明启动mvc
@ComponentScan("com.XXXX.service")
public class SwaggerConfig{
@Bean
public Docket apiDocket(){
//添加header参数
ParameterBuilder username = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
username.name("username")
.description("用户名")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false).build(); //header中的username
pars.add(username.build());
ParameterBuilder password = new ParameterBuilder();
password.name("password")
.description("密码")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false).build(); //header中的password
pars.add(password.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/* .apis(RequestHandlerSelectors.basePackage("com.XXX.service "))*/
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试接口")//文档说明
.version("1.0")//文档版本说明
.build();
}
}
3、添加实体类
@ApiModel(value="产品信息",description="产品信息")
public class Product{
private static final long serialVersionUID = 1L;
/** ID */
private Long id;
/** 产品名称 */
@ApiModelProperty(value = "产品名称", name="name", required = true)
private String name;
/** 产品型号 */
@ApiModelProperty(value = "产品型号", name="productClass", required = true)
private String productClass;
/** 产品ID */
@ApiModelProperty(value = "产品ID", name="productId", required = true)
private String productId;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getProductClass() {
return productClass;
}
public void setProductClass(String productClass) {
this.productClass = productClass;
}
public String getProductId() {
return productId;
}
public void setProductId(String productId) {
this.productId = productId;
}
@Override
public String toString() {
return "Product [id=" + id + ", name=" + name + ", productClass="
+ productClass + ", productId=" + productId + "]";
}
4、添加接口
@RestController
@Api(description="测试1controller")
@RequestMapping(value = {"/product/"})
public class ProductController extends BaseController{
@ApiOperation(value = "here is @ApiOperation value",tags = "测试接口2(here is @Api tags)", notes = "here is @ApiOperation notes")
@RequestMapping(value = "helloSwagger", method = RequestMethod.POST)
@ApiResponses({ @ApiResponse(code = 400, message = "error") })
public @ResponseBody String helloSwagger(
Product product){
return product.getName()+":"+product.getProductClass();
}
}
Ok，到这里，代码完成，项目跑起来
然后打开浏览器，输入http://localhost:8080/你的项目名/swagger-ui.html#/
就可以看到在线生成的接口文档。如果到这没问题，那么请在浏览器中输入
http://localhost:8080/你的项目名/v2/api-docs，如果网页返回json格式的字符串，那下一步导出才有可能。
Swagger文档导出
这两提供两种，一种是基于html和PDF格式的文件导出，另一种是基于doc格式的文件导出
1、基于基于html和PDF格式的文件导出
可以参见这个https://blog.csdn.net/java_collect/article/details/84480588 ，里面介绍的很详细，推荐使用方法2
2、基于doc格式导出
可以参见https://bbs.huaweicloud.com/blogs/120234，这里介绍得很详细
开发和文档一站式搞定。
关键点：
swagger对于文件上传的支持感觉并不是太友好，如果是单文件上传，那基本是没问题的，如果是多文件上传，那问题就不少。
单文件上传：
@ApiOperation(value = "here is @ApiOperation value",tags = "测试接口2(here is @Api tags)", notes = "here is @ApiOperation notes")
@RequestMapping(value = "helloSwagger", method = RequestMethod.POST,headers=”Content-Type=multipart/form-data”)
@ApiResponses({ @ApiResponse(code = 400, message = "error") })
@ApiImplicitParams({
@ApiImplicitParam(name = "file",value = "文件，",paramType = "formData",dataType = "file")
})
public @ResponseBody String helloSwagger(
Product product,
@RequestParam(value = "file")MultipartFile file){
…………
return product.getName()+":"+product.getProductClass();
}
测试的话，单文件可以直接在http://localhost:8080/你的项目名/swagger-ui.html#/上面测试
多文件上传：
@ApiOperation(value = "here is @ApiOperation value",tags = "测试接口2(here is @Api tags)", notes = "here is @ApiOperation notes")
@RequestMapping(value = "helloSwagger", method = RequestMethod.POST,headers=”Content-Type=multipart/form-data”)
@ApiResponses({ @ApiResponse(code = 400, message = "error") })
@ApiImplicitParams({
@ApiImplicitParam(name = "file",value = "文件，",paramType = "formData",allowMultiple=true,dataType = "file")
})
public @ResponseBody String helloSwagger(
Product product,
@RequestParam(value = "file")MultipartFile[] file){
…………
return product.getName()+":"+product.getProductClass();
}
测试的话，多文件只能在postman上面测试，swagger自带的在线测试是不支持多文件测试的。
用postman测试就ok了？不不不，这里还有坑，postman测试时，如果是有文件的情况下，file参数格式要选择file，如果要是文件为空的情况下，file参数格式要选择text，否则测试会报错