使用swagger生成API说明文档
本文由个人总结,如需转载使用请标明原著及原文地址
SwaggerDemo,jar包使用maven进行管理,还没了解maven的小伙伴可能有无法使用的情况
在做前后端分离的项目时,后端人员总是要写接口文档给其他使用者,大家都知道,写接口文档是一件吃力不讨好的事,而swagger就是为了解决这个问题而存在的,不仅能提供接口文档,还能提供简单的传参测试
要使用swagger,首先你要有一个spring项目
1.导包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
我这使用maven统一管理jar包,在pom.xml中加入上面两个dependency,maven就能自动下载对应jar包,不了解maven的小伙伴自行在百度上找jar包,然后手动导入项目
springfox-swagger2-vesion.jar
springfox-swagger-ui-vesion.jar
2.写一个swagger配置类
package cn.ycyy.controller;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author Devil
* @create 2018-09-26 19:16
*/
@EnableSwagger2
@ComponentScan(basePackages = {"cn.ycyy.controller"})
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("《SwaggerDemo的演示案例--》")//标题
.description("description:项目摘要")//描述
.termsOfServiceUrl("http://www.google.com.hk")//(不可见)条款地址,公司内部使用的话不需要配
.contact(new Contact("Devil", "https://blog.csdn.net/qq_36911145", "[email protected]"))//作者信息
.version("6.6.6")//版本号
.build();
}
}
创建的SwaggerConfig要继承WebMvcConfigurationSupport
@EnableSwagger2 | swagger2启动注解 |
@ComponentScan(basePackages = {"cn.ycyy.controller"}) | 指定需要生成API文档的类所在的包路径 |
@Configuration | 声明这是一个配置类 |
createRestApi方法不需要更改,主要用于swagger的初始化设置,包括扫描API注解路径等,用我提供的createRestApi默认扫描当前项目全部路径,这里的扫描与上面的@ComponentScan不同,这里扫描的不会显示在swagger-ui(swaggerAPI文档可视化界面,最后会说)上
apiInfo里的参数设置对应效果如下图所示
SwaggerConfig文件必须放在spring注解扫描器能扫描到的位置,例如说我的项目都放在cn.ycyy项目下,我指定扫描路径cn.ycyy那么spring就能把整个项目的注解都扫描到
<context:component-scan base-package="cn.ycyy">
<context:exclude-filter type="annotation"
expression="org.springframework.stereotype.Controller" />
</context:component-scan>
然后将项目启动发布到tomcat上,就能访问swaggerAPI了
访问的URL也是个固定的格式
http://ip地址:端口/项目名/swagger-ui.html#/
3.配置api生成
在先前说了,这里只会显示@ComponentScan(basePackages = {"cn.ycyy.controller"}),这个路径下的类生成的API
我的测试案例中只写了一个UserController所以这里只显示,UserController及里面的方法
UserController代码如下
package cn.ycyy.controller;
import cn.ycyy.bean.User;
import cn.ycyy.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.models.HttpMethod;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import javax.validation.Valid;
import java.util.List;
/**
* @author Devil
* @create 2018-09-28 15:36
*/
@Controller
@Api(value="aaaaaaa",description="User的相关信息接口")
public class UserController {
@Autowired
private UserService userService;
@RequestMapping("/getAll")
@ResponseBody
@ApiOperation(value="获取所有user",notes="获取所有user,无需参数", httpMethod = "POST")
public String getAll(){
//查出的所有部门信息
List<User> list = userService.selectAll();
return list.toString();
}
@RequestMapping("/getOne")
@ResponseBody
@ApiOperation(value="获取单个user",notes="获取单个user,需参数", httpMethod = "POST")
public String getOne(@Valid User user, BindingResult result){
//查出的所有部门信息
List<User> list = userService.selectBy(user);
return list.toString();
}
@RequestMapping("/getOneByName")
@ResponseBody
@ApiOperation(value="获取单个user",notes="获取单个user,需参数", httpMethod = "POST")
public String getOneByName(@ApiParam(value = "用户名", required = true)String name){
return "something";
}
}
在类上加上@Api注解
以下参数可不指定
value | 在swagger-ui上不显示 |
description | 在swagger-ui上有显示,可以当做备注使用,描述这个类的信息 在新版本的swagger2中description已被淘汰,可以用tags代替,但是不更改也不会影响使用 |
在方法上加上@ApiOperation注解
以下参数可不指定
value | 未展开状态方法备注信息 |
notes | 展开状态下方法备注信息,和value相比,value是未展开状态下的备注,一般会写的比较简短,而notes可以写的比较详细 |
httpMethod | 指定http模式,参数有"POST"、"DELETE"、"GET"、"HEAD"等 |
如果方法需要前端传递参数,可使用@ApiParam注解
value | 参数备注信息 |
required | 是否为必填项true为必填 |
如果方法用对象入参的话,在实体类中对属性加@ApiModelProperty注解
value | 类属性备注信息 |
例如我有个方法的参数用User,那么我User类如下配置
package cn.ycyy.bean;
import io.swagger.annotations.ApiModelProperty;
/**
* @author Devil
* @create 2018-09-28 15:24
*/
public class User {
@ApiModelProperty(value="用户名")
private String name;
@ApiModelProperty(value="密码")
private String password;
@ApiModelProperty(value="性别")
private String gender;
@ApiModelProperty(value="年龄")
private Integer age;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String getGender() {
return gender;
}
public void setGender(String gender) {
this.gender = gender;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}
效果如下所示
API文档中会将User自动分解成User的属性
4.注解全参数
以下是swagger2注解中的全参数,有兴趣可以都试试
@Api
Api 标记可以标记一个Controller类做为swagger 文档资源,使用方式
属性名称 |
备注 |
value |
url的路径值 |
tags |
如果设置这个值、value的值会被覆盖 |
description |
对api资源的描述 |
basePath |
基本路径可以不配置 |
position |
如果配置多个Api 想改变显示的顺序位置 |
produces |
For example, “application/json, application/xml” |
consumes |
For example, “application/json, application/xml” |
protocols |
Possible values: http, https, ws, wss. |
authorizations |
高级特性认证时配置 |
hidden |
配置为true 将在文档中隐藏 |
@ApiOperation每一个url资源的定义,使用方式
属性名称 |
备注 |
value |
url的路径值 |
tags |
如果设置这个值、value的值会被覆盖 |
description |
对api资源的描述 |
basePath |
基本路径可以不配置 |
position |
如果配置多个Api 想改变显示的顺序位置 |
produces |
For example, “application/json, application/xml” |
consumes |
For example, “application/json, application/xml” |
protocols |
Possible values: http, https, ws, wss. |
authorizations |
高级特性认证时配置 |
hidden |
配置为true 将在文档中隐藏 |
response |
返回的对象 |
responseContainer |
这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
httpMethod |
“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
code |
http的状态码 默认 200 |
extensions |
扩展属性 |
@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
属性名称 |
备注 |
name |
属性名称 |
value |
属性值 |
defaultValue |
默认属性值 |
allowableValues |
可以不配置 |
required |
是否属性必填 |
access |
不过多描述 |
allowMultiple |
默认为false |
hidden |
隐藏该属性 |
example |
举例子 |
@ApiImplicitParam对容器的描述
属性名称 |
备注 |
name |
属性名称 |
value |
属性值 |
defaultValue |
默认值 |
allowableValues |
可以不可配置 |
required |
是否属性必填 |
access |
不可过多描述 |
allowMutiple |
默认为false |
dataType |
数据类型 |
paramType |
参数类型 |
@ApiResponse
属性名称 |
备注 |
code |
http的状态码 |
message |
描述 |
response |
默认响应类 Void |
reference |
参考ApiOperation中配置 |
responseHeaders |
参考 ResponseHeader 属性配置说明 |
responseContainer |
参考ApiOperation中配置 |