如何使用Apache Camel正确配置OpenAPI的servers属性

基于Apache Camel + Spring框架搭建OpenAPI规范发布能力时，先后尝试三种配置方式设置服务地址：

• 使用restConfiguration代码方式配置
• 在application.yaml中添加对应配置属性
• 在应用类上添加@OpenApiProperty注解
  但自动生成的OpenAPI YAML文档中servers节点的url值始终为空，异常生成片段如下：

- servers
  - url: ""

当前使用的application.yaml配置内容如下：

platform:
  # not used
  urlrewrite:
    enabled: false
    token: ${LOCAL_TOKEN:}
    apim:
      token_ep: ${x/token}
      client:
        username: ${apim_client_username:}
        password: ${apim_client_password:}
        consumerKey: ${apim_client_id:}
        consumerSecret: ${apim_client_secret:}

  endpointsOrchestrated:
    server: myServer
    emr-endpoint: xxxxxxxx
  triggerName: ${PLATFORM_MODULE_ID}
  env: dev
  domain: ${PLATFORM_MODULE_DOMAIN}

openapi:
  title: My Sample api
  version: 1.0.0

camel:
  dataformat:
    jackson:
      auto-discover-object-mapper: true
  springboot:
    tracing: false
  rest:
    host: myhost.com
    port: 8080

spring:
  application:
    name: aaa
  profiles:
    active: ${ENV:local}

server:
  servlet:
    context-path: /
  port: ${TOMCAT_PORT:8080}
  host: localhost
  # MAX HTTP THREADS
  tomcat:
    threads:
      max: ${MAIN_HTTP_THREADS:200}

需要找到正确配置方式，让生成的OpenAPI文档中servers.url属性正常生效。

Camel OpenAPI模块不会自动读取camel.rest.host、camel.rest.port作为server地址，这两个配置是给Camel Rest生产者调用外部服务用的，和OpenAPI生成逻辑无关，按以下方式配置即可生效：

• 配置文件方式：在camel.rest节点下补充OpenAPI专用的地址配置项

camel:
  rest:
    host: myhost.com
    port: 8080
    # OpenAPI模块读取的服务地址配置
    api-host: myhost.com
    api-port: 8080
    scheme: http
    # 如果有上下文路径补充该配置
    api-context-path: /

• 代码配置方式：调用restConfiguration的对应set方法显式传值，不要只设置普通host/port

restConfiguration()
    .component("servlet")
    .host("myhost.com")
    .port("8080")
    // 以下是OpenAPI server地址必填配置
    .apiHost("myhost.com")
    .apiPort("8080")
    .scheme("http")
    .apiContextPath("/")
    .apiContextPath("/v3/api-docs");

• 自定义全路径场景：如果服务前置网关、有特殊路径前缀，可以直接在openapi节点下直接指定完整servers列表，该配置优先级最高

openapi:
  title: My Sample api
  version: 1.0.0
  configuration:
    servers:
      - url: http://myhost.com:8080
        description: 开发环境服务地址

注意：@OpenApiProperty注解仅用于补充接口、字段的元数据说明，无法配置全局server地址，该用法本身不生效。

配置完成重启服务后，生成的OpenAPI文档中servers.url会自动填充为配置值，不再返回空字符串。

内容的提问来源于stack exchange，提问作者Aleksandar Milosevic