在 Liberty 服务器上发现 REST API 文档

您可以使用 API 发现功能部件来发现 Liberty 服务器上的 REST API 文档,以了解哪些 REST API 可用。可以使用 Swagger 用户接口来调用可用的 REST 端点。

过程

  1. 在您要查找其可用 REST API 的 Liberty 服务器的 server.xml 文件中,将 apiDiscovery-1.0 功能部件添加至功能部件管理器。

    apiDiscovery-1.0 功能部件在产品中启用 REST API 发现捆绑软件。此功能部件还会展示 JMX 之类的 Liberty REST 端点(如果服务器配置使用 restConnector-1.0 功能部件)和集合体(如果服务器配置使用 collectiveController-1.0 功能部件)中的文档。

    确保服务器配置具有所部署应用程序需要的所有功能部件,例如,servlet-3.0jsp-2.2 等等。还应确保端口和用户注册表设置对于所部署应用程序而言是正确的。

    以下 server.xml 文件具有 apiDiscovery-1.0 功能部件:

    <server>
        <featureManager>
            <feature>apiDiscovery-1.0</feature>
        </featureManager>
    
        <httpEndpoint id="defaultHttpEndpoint"
                      host="*"
                      httpPort="8010"
                      httpsPort="8020"/>
    
        <keyStore id="defaultKeyStore" password="Liberty"/>
      
        <basicRegistry id="basic" realm="ibm/api">
            <user name="bob" password="bobpwd" />
        </basicRegistry>
    </server>
  2. 展示 Liberty REST 端点中的 Swagger 2.0 文档。

    如果 Web 应用程序包含 javax.ws.rs.core.Application 类的两个或更多实例,可正确地与 API 发现功能部件配合使用,那么每个应用程序都需要唯一 javax.ws.rs.@ApplicationPath 值或 web.xml 文件中定义的 url-mapping。

    启用 apiDiscovery-1.0 功能部件以将当前文档与注释扫描期间找到的文档进行合并。产品在 Web 模块中搜索 META-INF/stub/swagger.jsonMETA-INF/stub/swagger.yaml 文件。如果功能部件找到这两个文件其中的任何一个,那么它将生成包含文件内容以及 Web 模块中所有 JAX-RS 和 Swagger 注释的 Swagger 文档。可以使用此功能部件来记录非 JAX-RS servlet,因为该文档将自动与 JAX-RS 部分合并。可通过以下两种方式中的任何一种配置 API 文档的位置:

    • 使用 SPI com.ibm.wsspi.rest.api.discovery.APIProvider 接口的 getDocumentation 方法。

      getDocument 方法允许扩展功能部件中的 OSGi 捆绑软件将 REST API 文档添加至整个主文档。对于此发行版,唯一受支持 DocType 为 DocType.Swagger_20_JSONDocType.Swagger_20_YAML。此接口的实现者可将序列化 JSON 或 YAML 文档返回为 java.lang.String 值,或者可以将文件引用(带有前缀 file:///)传递至 JSON 或 YAML 文件位置。

    • 使用所部署 Web 应用程序。

      每个 Web 模块可继续自己的 REST API 文档。企业应用程序 (EAR) 文件内部的多个 WAR 文件可具有不同 Swagger 2.0 文档。

      公开 Web 模块文档的最简单方法是将 swagger.jsonswagger.yaml 文件包含在对应的 META-INF 文件夹中。部署应用程序期间,API 发现功能部件会针对每个 Web 模块查找 META-INF/swagger.json 值。如果找不到 META-INF/swagger.json 值,那么 API 发现功能部件将查找 META‐INF/swagger.yaml 值。

      展示 Web 模块的 REST API 文档的另一方法是在 server.xml 配置文件中进行。将每个 Web 模块的 webModuleDoc 元素放置在父 apiDiscovery 元素中;例如:

      <apiDiscovery>
         <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" />	
         <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" />
         <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" />
      </apiDiscovery>

      webModuleDoc 元素必须具有 contextRoot 属性,此属性唯一标识您要展示其文档的 Web 模块。

      可选属性 enabled 用于对 Web 模块开启和关闭 API 发现。此属性的缺省值为 true

      docURL 属性指定用于查找 Web 模块文档的位置。docURL 值可以正斜杠 (/) 开头,以使 URL 相对于上下文根;例如,/30ExampleServletInEar/swagger.jsondocURL 值也可以 httphttps 开头,以表示用于标识文档完整位置的绝对 URL。

      如果 Web 应用程序未提供 swagger.jsonswagger.yaml 文件,并且应用程序包含 JAX-RS 注释资源,那么可以自动生成 Swagger 文档。服务器配置必须具有 apiDiscovery-1.0 功能部件及 jaxrs-1.1jaxrs-2.0 功能部件;例如:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.0</feature>
      </featureManager>
      产品将扫描 Web 应用程序中的所有类以查找 JAX-RS 和 Swagger 注释(搜索带有 @Path@Api@SwaggerDefinition 注释的类)。产品还将在 Web 应用程序部署或启动期间自动生成相应的 Swagger 文档。

      还可以使用 apiDiscovery-1.0 功能部件来将先前生成的文档与注释扫描期间找到的文档进行合并。产品在 Web 模块中搜索 META-INF/stub/swagger.jsonMETA-INF/stub/swagger.yaml 文件。如果功能部件找到这两个文件其中的任何一个,那么它将生成包含该文件内容以及 Web 模块中所有 JAX-RS 和 Swagger 注释的 Swagger 文档。可以使用此功能部件来记录非 JAX-RS servlet,因为该文档将自动与 JAX-RS 部分合并。

      还可以使用此方法来绕过注释限制,例如,公开安全性定义。例如,以下 swagger.jsoninside META-INF/stub 允许注释引用这些定义:

      {
        "swagger" : "2.0",
        "securityDefinitions" : {
          "petstore_auth" : {
            "type" : "oauth2",
            "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog,"
            "flow" : "implicit",
            "scopes" : {
              "write_pets" : "modify pets in your account",
              "read_pets" : "read your pets"
            }
          },
          "api_key" : {
            "type" : "apiKey",
            "name" : "api_key",
            "in" : "header"
          }
        }
      }
  3. 发现 API 文档。

    配置 API 文档的位置后,可通过以下方式发现该文档:

    • 使用 GET https://host:https_port/ibm/api/docs 端点。

      此端点提供有效 Swagger 2.0 文档,其所有可用 Liberty REST API 已合并至单个文档。对于要通过程序浏览可用 API 集的使用者应用程序(例如,API 管理解决方案),这很有用。包含带有 application/yaml 值的可选 Accept 头可以提供 YAML 格式的 Swagger 2.0 文档。此端点有一个名为 root 的可选多基数查询参数,此参数可用于过滤所发现的上下文根。例如,对 GET https://host:https_port/ibm/api/docs?root=/myApp 的调用将检索仅具有 myApp 上下文根的文档的 Swagger 2.0 文档。

    • 使用 GET https://host:https_port/ibm/api/explorer 端点。

      此端点提供富吸引力的已渲染 HTTP 页面来显示 /ibm/api/docs URL 中的内容。此页面遵循标准在线样本 (http://petstore.swagger.io/) 的模式,所以用户可调用 REST API。此端点帮助您探查 Liberty 服务器上的可用 REST API,并且可能会从页面调用这些 API。页面上的过滤器输入框允许使用上下文根的逗号分隔列表来过滤内容。此过滤的工作方式与 root 查询参数类似。可以通过提供所需的输入值并单击尝试按钮来测试 API。

    • 对于集合体控制器,请使用 GET https://host:https_port/ibm/api/collective/explorer 端点。

      集合体控制器上的此端点提供富吸引力的已渲染 HTTP 页面来显示 /ibm/api/collective/docs URL 中的内容。此端点帮助您探查整个集合体上的可用 REST API,并且可能会从页面调用这些 API。页面上的过滤器输入框允许使用上下文根和服务器标识的逗号分隔列表来过滤内容。服务器标识的格式为 "hostName,userDir,serverName"。必须为服务器标识添加引号 (")。如果要使用尝试按钮测试 API,那么您需要在成员服务器的 server.xml 中设置跨源请求共享 (CORS)。

      例如,在提供 API /IBMJMXConnectorREST/mbeanCount 的成员服务器的 server.xml 中,需要以下片段:

      <cors domain="/IBMJMXConnectorREST/mbeanCount"
                allowedOrigins="https://<controller_hostname>:<https_port>"
                allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS"
      		  allowedHeaders="Content-Type,api_key,Authorization"
      		  allowCredentials="true"
              />

      有关设置 CORS 的更多信息,请参阅在 Liberty 服务器上配置跨源请求共享

      注: CORS 需求仅适用于 Swagger UI 的集合体版本 (https://host:https_port/ibm/api/collective/explorer)。
    启用 apiDiscovery-1.0 功能部件后,ObjectName 值为 WebSphere:feature=apiDiscovery,name=APIDiscovery 的管理 bean (MBean) 在 Liberty MBeanServer 中注册。此 MBean 提供以下属性:
    • DocumentationURL 属性是 /ibm/api/docs 端点的完整 URL,它显示原始 JSON 或 YAML 文档。
    • ExplorerURL 属性是 /ibm/api/explorer 端点的完整 URL,它显示文档的呈现 UI。

    可以使用此 MBean 来了解 REST API 发现是否已启用以及客户机可以在何处访问该功能部件。


用于指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: Monday, 5 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-libcore-mp&topic=twlp_api_discovery
文件名:twlp_api_discovery.html