有了Swagger2,再也不用为写Api文档头疼了
1、为什么要写Api文档
现在,前后端分离的开发模式已经非常流行,后端开发工程师只负责完成后端接口,前端页面的开发和渲染完全由前端工程师完成。
问题来了,前端工程师怎么知道后端接口的具体定义呢?答案是由后端工程师撰写。
2、写Api文档很头疼吗
答案是一定的,这对后端工程师来说,是额外的工作,编码已经很耗费精力了,这时前端工程师来催文档,不头疼才怪:),当然这也不是前端工程师的问题,都是为项目的进度着急。
3、Swagger2
现在好了,一个自动撰写Api文档的神器出现了,他就是 Swagger2,Swagger2通过美观的WEB界面展示了所有接口的定义,非常方便,还能直接在界面上进行测试调用,有助于调试。
后端工程师,定义好接口,加几个注解,便能自动生成在线接口定义,前端工程师可以实时的看到。
下面就来讲讲如何把 Swagger2 整合到项目中来。
4、接口介绍
这里以一个简单的接口作为例子,接口的功能是输入用户ID,获取用户数据。
5、引入依赖
<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>
6、增加Swagger2配置类
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; 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; @Configuration @EnableSwagger2 public class Swagger2 { // swagger2配置 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2 .apiInfo(apiInfo()) // 用于定义api文档汇总信息 .select() .apis(RequestHandlerSelectors .basePackage("cn.zhuifengren.controller")) // 指定扫描的controller包 .paths(PathSelectors.any()) // 所有controller .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("hello工程接口api") // 文档页标题 .contact(new Contact("hello", "", "")) // 联系人信息 .description("专为hello工程提供的api文档") // 详细信息 .version("1.0.0") // 文档版本号 .termsOfServiceUrl("") // 网站地址 .build(); } }
7、在Controller类中增加Swagger2注解
import cn.zhuifengren.model.Result; import cn.zhuifengren.model.User; import cn.zhuifengren.service.UserService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/user") @Api(value = "UserController", tags = "用户接口") public class UserController { @Autowired private UserService userService; @GetMapping("/info/{id}") @ApiOperation(value = "获取用户信息") public Result<User> getUserInfo(@ApiParam(value = "用户ID") @PathVariable("id") String id) { User userInfo = userService.getUserInfo(id); Result<User> result = new Result<>(); result.setCode(200); result.setMessage("success"); result.setData(userInfo); return result; } }
其中 @Api注解 放在类上,用于对类的描述,@ApiOperation注解 放在方法上,用于对接口方法的描述。
8、模型类中增加Swagger2注解
import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "用户实体", description = "用户实体") public class User { @ApiModelProperty(value = "用户id", name = "id", example = "1") private String id; @ApiModelProperty(value = "用户姓名", name = "name", example = "小李") private String name; @ApiModelProperty(value = "用户年龄", name = "age", example = "36") private Integer age;
其中 @ApiModel注解 放在类上,用于对模型类的描述,@ApiModelProperty注解 放在属性上,用于对模型属性的描述。
9、启动项目查看效果
启动项目后,进入地址:http://localhost:8080/swagger-ui.html,即可看到Swagger2 WEB页面,点击【Try it out】按钮,还可以对接口进行测试,是不是很方便呢,赶快去用一下吧