引言
代码已提交到Github，有兴趣的同学可以看看：https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo
随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。
提供的对象有： PC端、微信端、H5端、移动端（安卓和IOS端）
传统的API文档编写存在以下几个问题：
- 对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
- API接口返回信息不明确。
- 大公司中肯定会有专门文档服务器对接口文档进行更新。
- 缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
- 接口文档太多，不便于管理。
为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。
1. Swagger
Swagger Demo的代码已提交到Github，有兴趣的同学可以看看：https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo
Swagger具有以下优点：
- 功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
- 及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
- 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。
1.1 Swagger集成步骤
1.新建Maven项目Swagger-Demo
2.添加Maven依赖
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.1.RELEASE</version> </parent> <dependencies> <!-- SpringBoot整合Web组件 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--SpringBoot swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <!--SpringBoot swagger2 -UI --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> </dependencies>
3.添加SwaggerConfig
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // api扫包 .apis(RequestHandlerSelectors.basePackage("com.ylw.swagger.api")).paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("学生信息管理系统").description("对学生信息进行管理") .termsOfServiceUrl("http://www.xxx.com") // .contact(contact) .version("1.0").build(); } }
4.API注释
@RestController @RequestMapping("api") @Api("学生信息管理系统相关的api") public class StudentController { private static final Logger logger = LoggerFactory.getLogger(StudentController.class); @ApiOperation(value = "新增学生信息", notes = "新增学生信息：用户名、性别、年龄") @ApiResponses({ @ApiResponse(code = 200, message = "校验成功"), @ApiResponse(code = 400, message = "校验失败"), @ApiResponse(code = 401, message = "参数不合法"), @ApiResponse(code = 500, message = "系统异常"), }) @ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"), @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"), @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"), }) @RequestMapping(value = "/addStudent/{userName}/{sex}/{age}", method = RequestMethod.POST) public Response addStudent(@PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) { logger.info("新增学生信息操作"); return new Response(200, "新增学生信息成功！"); } @ApiOperation(value = "删除学生信息", notes = "删除学生信息：用户名、性别、年龄") @ApiResponses({ @ApiResponse(code = 200, message = "校验成功"), @ApiResponse(code = 400, message = "校验失败"), @ApiResponse(code = 401, message = "参数不合法"), @ApiResponse(code = 500, message = "系统异常"), }) @ApiImplicitParams({ @ApiImplicitParam(name = "uuid", value = "学生id", required = true, dataType = "String"), }) @RequestMapping(value = "/delStudent/{uuid}", method = RequestMethod.DELETE) public Response delStudent(@PathVariable String uuid) { logger.info("删除学生信息操作"); return new Response(200, "删除学生信息成功！"); } @ApiOperation(value = "修改学生信息", notes = "修改学生信息：用户名、性别、年龄") @ApiResponses({ @ApiResponse(code = 200, message = "校验成功"), @ApiResponse(code = 400, message = "校验失败"), @ApiResponse(code = 401, message = "参数不合法"), @ApiResponse(code = 500, message = "系统异常"), }) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"), @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"), @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"), @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"), }) @RequestMapping(value = "/updateStudent/{id}/{userName}/{sex}/{age}", method = RequestMethod.POST) public Response updateStudent(@PathVariable String id, @PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) { logger.info("修改学生信息操作"); return new Response(200, "修改学生信息成功！"); } @ApiOperation(value = "查询学生信息", notes = "查询学生信息：用户名、性别、年龄") @ApiResponses({ @ApiResponse(code = 200, message = "校验成功"), @ApiResponse(code = 400, message = "校验失败"), @ApiResponse(code = 401, message = "参数不合法"), @ApiResponse(code = 500, message = "系统异常"), }) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"), }) @RequestMapping(value = "/getStudent/{id}", method = RequestMethod.GET) public Response getStudent(@PathVariable String id) { logger.info("修改学生信息操作"); return new Response(200, "修改学生信息成功！"); } }
5.浏览器访问
访问网址：http://localhost:8099/swagger-ui.html#/，可以看到接口文档自动生成了。
6.展开其中的一个接口
可以看到描述：
