操作场景
TSF 框架在微服务注册时,会自动收集并注册微服务提供的 API 接口,用户可通过 TSF 控制台实时掌握当前微服务提供的 API 情况。API 注册功能基于 OpenApi Specification 3.0 规范注册 API 元数据信息。 用户在查看 API 接口的同时,可查看到 API 出入参数据结构信息。
前提条件
添加依赖
向工程中添加
spring-cloud-tsf-starter
依赖并开启 @EnableTsf
注解。注意
1. 向工程中添加依赖。
在
pom.xml
中添加以下代码:<dependency><groupId>com.tencent.tsf</groupId><artifactId>spring-cloud-tsf-starter</artifactId><version><!-- 调整为 SDK 最新版本号 --></version></dependency>
spring-cloud-tsf-starter
中包含了服务注册发现、服务路由、服务鉴权、服务限流、服务熔断、服务容错、服务监控、分布式配置、调用链功能。
2. 向 Application 类中添加注解 @EnableTsf
:// 下面省略了无关的代码@SpringBootApplication@EnableTsfpublic class ProviderApplication {public static void main(String[] args) {SpringApplication.run(ProviderApplication.class, args);}}
配置选项
API 注册功能基于 Swagger 原生规范实现,提供多个配置以适配 Swagger 不同配置应用场景,可用配置如下表所示:
配置项 | 类型 | 必填 | 默认值 | 说明 |
tsf.swagger.enabled | Boolean | 否 | true | 是否开启 TSF API 注册功能 |
tsf.swagger.basePackage | String | 否 | ApplicationMainClass 所在包路径 | 注册 API 的扫描包路径。 推荐将 ApplicationMainClass 写在外层 Package |
tsf.swagger.excludePath | String | 否 | (空) | 排除扫描的包路径 |
tsf.swagger.group | String | 否 | default | swagger docket 分组 |
tsf.swagger.doc.auto-startup | Boolean | 否 | true | 是否开启 Swagger 相关暴露接口。如果设置为 false,则不暴露相关接口,以下路径将会屏蔽并返回403: /v2/api-docs /swagger-ui.html /swagger-resources/ /webjars/springfox-swagger-ui/ |
代码和示例
SDK 会自动扫描 API 的 path 和 出入参。
如果需要上报 API 的描述,需要
import io.swagger.annotations.ApiOperation;
,同时在 API 上加上注解 @ApiOperation(value = "url路径值",notes = "对api资源的描述")
。如果不关注 API 描述,可以不设置 @ApiOperation。package com.tsf.demo.provider.controller;// 省略掉部分 importimport io.swagger.annotations.ApiOperation;import com.tsf.demo.provider.config.ProviderNameConfig;@RestControllerpublic class ProviderController {private static final Logger LOG = LoggerFactory.getLogger(ProviderController.class);@Autowiredprivate ProviderNameConfig providerNameConfig;@ApiOperation(value= "/echo/{param}", notes = "notes") // notes 对应 API 描述@RequestMapping(value = "/echo/{param}", method = RequestMethod.GET)public String echo(@PathVariable String param) {LOG.info("provider-demo -- request param: [" + param + "]");String result = "request param: " + param + ", response from " + providerNameConfig.getName();LOG.info("provider-demo -- provider config name: [" + providerNameConfig.getName() + ']');LOG.info("provider-demo -- response info: [" + result + "]");return result;}}
说明
依赖 spring-cloud-tsf-starter 后,将同时为您开启查看 API 文档能力,您可以通过
ip:port/swagger-ui.html
页面进行 API 查看。若访问不成功,建议更新到最新版本的 SDK。
如果您不需要这个能力,可以在依赖中进行排除,示例如下:<dependency><groupId>com.tencent.tsf</groupId><artifactId>spring-cloud-tsf-starter</artifactId><exclusions><exclusion><artifactId>springfox-swagger-ui</artifactId><groupId>io.springfox</groupId></exclusion></exclusions></dependency>
排除后,不影响在 TSF 服务治理 > 接口列表中查询 API 的能力,仅仅不支持通过
ip:port/swagger-ui.html
查看。