随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。
来源：PC端、微信端、H5端、移动端（安卓和IOS端）
传统的API文档编写存在以下几个痛点：
对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
API接口返回信息不明确
大公司中肯定会有专门文档服务器对接口文档进行更新。
缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
接口文档太多，不便于管理
为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。
Swagger具有以下优点
1.功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
2.及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
3.整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.1.RELEASE</version> </parent> <!-- 管理依赖 --> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Finchley.M7</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <!-- SpringBoot整合Web组件 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- SpringBoot整合eureka客户端 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> <!-- swagger2 一个做ui 一个做提供接口的--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> </dependencies> <!-- 注意： 这里必须要添加， 否者各种依赖有问题 --> <repositories> <repository> <id>spring-milestones</id> <name>Spring Milestones</name> <url>https://repo.spring.io/libs-milestone</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories>
Controller:
package com.toov5.api; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; @Api("swaggerdemo控制器") //接口描述 @RestController public class SwaggerController { @ApiOperation(value = "swagger演示接口") //具体描述 @GetMapping("/swaggerIndex") public String swaggerIndex() { return "swaggerIndex"; } }
创建config包，并且贴入依赖：
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // api扫包 .apis(RequestHandlerSelectors.basePackage("com.itmayiedu.api")).paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("每特教育|蚂蚁课堂 微服务电商系统").description("每特教育|蚂蚁课堂 Java分布式&微服务培训") .termsOfServiceUrl("http://www.itmayiedu.com") // .contact(contact) .version("1.0").build(); } }
yml:
###服务启动端口号 server: port: 6060 ###服务名称 spring: application: name: springboot-swagger
访问：
传入参数型的接口：
package com.toov5.api; import org.aspectj.weaver.tools.Trace; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; @Api("swaggerdemo控制器") //接口描述 @RestController public class SwaggerController { @ApiOperation(value = "swagger演示接口") //具体描述 @GetMapping("/swaggerIndex") public String swaggerIndex() { return "swaggerIndex"; } @ApiOperation(value = "获取会员信息接口") //具体描述 @ApiImplicitParam(name="userName",value="用户信息参数",required=true,dataType="String") //传入的参数 ,描述 , 必须传递true , 类型String @GetMapping("/getMembe") public String getMember(String userName) { System.out.println(userName); return "userName"+userName; } }
点击try out
然后传入参数, excute执行一下
原创文章，作者：ItWorker，如若转载，请注明出处：https://blog.ytso.com/tech/pnotes/16134.html