您觉得本文档还缺少什么内容？可以自己补充~

本项目的Swagger 文档UI采用 knife4j ,后端注解使用Springfox + Swagger相关注解.

对于bc-cloud项目,访问每个服务的 http://ip:端口/doc.html 都能直接访问服务的文档。 而 http://ip:8760/api/gate/doc.html , 则访问网关聚合后的文档，区别在于

  1. 网关聚合文档可以看到整个项目所有服务的文档（前提是后台服务是正常启动状态）, 调试时请求会通过网关转发, 所以必须携带token、Tenant、Client等请求头
  2. 独立服务都文档只有自己服务都文档, 所以需要携带userid、Tenent等请求头 (请求通过网关过滤器时, 会将请求头中的 token 解析成userid、Client(密文)解析成 Client(明文), 请求到达后端服务时, 全局拦截器将userid,Tenant,Client 等请求头封装进LocalThread )
  3. 通过网关路由的接口，后端服务长时间不返回时, 网关会超时

bc-cloud全部项目启动成功后，会有几个swagger地址：

认证服务文档：http://127.0.0.1:8773/doc.html
租户服务文档：http://127.0.0.1:8778/doc.html
权限服务文档：http://127.0.0.1:8764/doc.html
文件服务文档：http://127.0.0.1:8765/doc.html

gateway网关聚合文档：http://127.0.0.1:8760/api/doc.html

通过swagger文档调用接口

每个接口请求时，请求头中都要携带封装了用户身份的token请求头，请求通过网关路由到后端具体的服务，并在网关的系统会将请求头中的token信息解析成用户信息(userId, orgId, name, account 等信息)，再次封装到请求头中。

详细流程:

通过上图可以知道，正常流程中，调用后端请求时，需要在请求头中携带token，在网关解析并验证token、解码tenant后，将用户id、用户账号、姓名、解码后的tenant等基础信息封装到请求头中，转发请求到具体的 业务服务中，而每个业务服务都有一个上下文拦截器HeaderThreadLocalInterceptor, 用于将请求头中的用户ID、租户编码等信息封装到LocalThread中。 这样，当请求到达Controller->Service->Mapper 层时，程序就能通过LocalThread获取当前登录人的信息和租户编码用于切换数据源和业务处理了。

所以，直接调用业务服务的swagger文档时，不需要传递token 和tenant，需要通过swagger的全局参数设置配置tenant、userid、name、account等信息！

通过网关的swagger文档调用接口

需要先调用登录接口获取用户token，然后调用业务接口时，传递token、租户编码、base64加密的Client。

  1. 调用方法生成加密后的Client
前端调用： Base64.encode('bc_web:bc_web_secret')  的值即为  YmNfd2ViOmJjX3dlYl9zZWNyZXQ
后端调用： Base64.getEncoder().encodeToString(new String("bc_web:bc_web_secret").getBytes())
  1. 打开网关聚合文档：http://127.0.0.1:8760/api/gate/doc.html 。如图所示点击 oauth-认证服务 - 登录接口 - 登录接口 - 调试 - 填写请求头 - 填写账号密码 - 点击发送 
# 请求头：
Authorization: Basic test
Tenant: 0000
Client: Basic YmNfd2ViOmJjX3dlYl9zZWNyZXQ
# 参数：
{
    "account": "bcAdmin",
    "code": "",
    "grantType": "password",
    "key": "",
    "password": "bcAdmin",
    "refreshToken": ""
}

4，复制返回 登录接口 返回的token , 将它作为接口的的请求参数. 5, 调用任意接口, 除特殊接口外，任意接口都需要在请求头设置 Authorization、Tenant、Client 3个参数。

  • Client 用于验证client端信息，封装了ClientId 和 ClientSecret 信息，如PC端 、 App 、小程序等不同的UI层，需要各自在应用管理申请应用信息后，方可调用。
参数格式为：Client: Basic  YmNfd2ViOmJjX3dlYl9zZWNyZXQ
注意： Basic 后面有个空格
  • tenant 用于验证租户信息
参数格式为：Tenant: 0000
  • Authorization 用于验证用户信息，存放的是jwt加密后的 用户信息。 参考：TokenUtil
参数格式为：token: Bearer xxxx
注意： Bearer 后面有个空格

单独调用业务服务时，无需配置token 和 Authorization， 但需要配置明文 tenant 和 userid

  1. 访问以下任意服务文档
认证服务文档：http://127.0.0.1:8773/doc.html
租户服务文档：http://127.0.0.1:8778/doc.html
权限服务文档：http://127.0.0.1:8764/doc.html
文件服务文档：http://127.0.0.1:8765/doc.html
  1. 发送请求前, 切换到请求头部 页面, 设置Tenant、userid 等参数.

新服务如何接入swagger文档

  1. server 模块加入依赖
<dependency>
    <groupId>com.becypress.basic</groupId>
    <artifactId>bc-swagger2-starter</artifactId>
</dependency>
  1. 如有需要, 修改全局的 common.yml 配置文件 . 参考 SwaggerProperties 类上的注释.
bc:
  # swagger 文档通用配置， 主要配置了全局参数、版本号信息、联系人信息  详情看: SwaggerProperties
  swagger:
    license: Powered By becypress
    version: 1.0.0
    global-operation-parameters:
      - name: Authorization
        description: 用户身份token
        modelRef: String
        parameterType: header
        required: true
        # 默认值只是方便本地开发时，少填参数，生产环境请禁用swagger或者禁用默认参数
        defaultValue: "Bearer test"
      - name: Client
        description: 客户端信息
        modelRef: String
        parameterType: header
        required: true
        defaultValue: "Basic YmNfd2ViOmJjX3dlYl9zZWNyZXQ"
      - name: Tenant
        description: 租户编码
        modelRef: String
        parameterType: header
        required: true
        defaultValue: "0000"
  echo:  #详情看: EchoProperties
    # 是否启用 远程数据 手动注入
    enabled: true
    # 是否启用 远程数据 注解AOP注入
    aop-enabled: true
  security: #详情看: SecurityProperties
    # 全局开启 uri 权限
    enabled: true
    # uri权限调用oauth服务的调用方式
    type: FEIGN
    # uri权限验证时，是否区分@PreAuth(value="xxx")的大小写
    caseSensitive: false
  log:  # 详情看：OptLogProperties
    # 开启记录操作日志
    enabled: true
    # 记录到什么地方  DB:mysql LOGGER:日志文件
    type: DB
  captcha:
    # 登录界面的验证码配置 详情看：CaptchaProperties
    type: SPEC
    width: 158
    height: 58
    len: 4
    charType: 2
  async:
    corePoolSize: 2
    maxPoolSize: 50
    queueCapacity: 10000
    keepAliveSeconds: 300
    threadNamePrefix: 'bc-async-executor-'


# knife4j 文档通用配置 详情看: Knife4jProperties
knife4j:
  enable: true
  setting:
    enableReloadCacheParameter: true
    enableVersion: true
    enableDynamicParameter: true
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: bc-cloud

  1. knife4j 提供了生产环境禁用、访问密码、修改文档基础样式等功能, 更多功能参考: knife4j

  2. SwaggerProperties 提供了动态配置docket文档的能力, 修改 bc-xxx-server.yml 配置文件配置多个文档group.

bc:
  swagger:
    docket:
      tenant:
        title: 租户模块
        base-package: com.becypress.product.tenant.controller

  1. 启动动项目, 访问 http://ip:port/doc.html

  2. 在网关配置文件中加入新服务的路由即可使用网关聚合文档.

  - id: xxx
    uri: lb://bc-xxx-server   // 新服务名
    predicates:
      - Path=/xxx/**
    filters:
      - StripPrefix=1
  1. 访问 http://ip:port/api/doc.html 时, 网关通过 SwaggerResourceConfig 类进行聚合. 这个类的实现原理是通过读取网关的路由配置, 然后通过restTemplate请求后端服务的文档数据, 所以当后端服务未启动时, 是无法聚合文档的

results matching ""

    No results matching ""