Spring Cloud之Swagger2 API接口管理
随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的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("Toov5|微服务电商系统").description("demo")
.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执行一下