SpringBoot整合Swagger2
SpringBoot整合Swagger2
相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。
手写Api文档的几个痛点:
文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口,通常需要使用工具,比如postman
接口文档太多,不好管理
Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。
一、添加依赖
<!-- swagger2 配置 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency>
二、 添加Swagger配置类
其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。
@Configuration @EnableSwagger2 public class Swagger2 { /** * @Description:swagger2的配置文件,这里可以配置swagger2的一些基本的内容 比如扫描的包等等 */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).slect() .apis(RequestHandlerSelectors.basePackage("com.vivo.controler")) .paths(PathSelectors.any()).build(); } /** * @Description: 构建 api文档的信息 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() // 设置页面标题 .title("使用swagger2构建小程序后端api接口文档") // 设置联系人 .contact(new Contact("likang", "http://", "@163.com")) // 描述 .description("欢迎访问小程序接口文档,这里是描述信息") // 定义版本号 .version("1.0").build(); } }
用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。
Application.class 加上注解@EnableSwagger2 表示开启Swagger
三、Controller层
类加上@Api的注解
方法加上@ApiOperation的注解
查看这个方法,参数有username和password。接下来对参数进行限制
四、Pojo层
实体类加上@ApiModel的注解
实体属性加上@ApiModelProperty的注解
前端不需要显示的属性加上@ApiModelProperty(hidden=true)
@Table(name = "t_user") @ApiModel(value="用户对象", description="这是用户对象") public class TUser { @ApiModelProperty(hidden=true) private String id; @ApiModelProperty(value="用户名", name="username", example="zhangsan", required=true) private String username; @ApiModelProperty(value="密码", name="password", example="123456", required=true) private String password; }
五、Swagger2文档
启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html
这时候就可以在Swagger2****文档,看见我们一一写的对应的注释,具体里面的内容以及接口测试。
点击/regist进行测试,可以看到非常详情
Swagger注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数