Liberty 服务器上发现 REST API 文档

您可以使用 API 发现功能部件来发现 Liberty 服务器上的 REST API 文档,以了解哪些 REST API 可用。可以使用 Swagger 用户界面来启动可用的 REST 端点。
[18.0.0.1 and later]提示: 可以使用 openapi-3.0 功能部件来发现 REST API 文档。openapi-3.0 功能部件可归类为 apiDiscovery-1.0 功能部件的下一个版本。您可以将使用 apiDiscovery-1.0 创建的 Swagger V2 文档更新为 OpenAPI V3。请参阅 使用 OpenAPI 生成 REST API 文档

过程

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

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

    确保服务器配置具有所部署应用程序需要的所有功能部件,例如,jaxrs-2.0。修改端口,以便服务器可以打开其 HTTP 端口。

    如果要显示专用 REST API 文档,请在 server.xml 文件中配置密钥库服务对象条目和用户注册表设置。

    [17.0.0.1 and later]但是,如果希望仅显示公用 REST API 文档,那么只有在您希望通过 HTTPS 访问文档时,才添加密钥库对象条目。通过 HTTP 访问公共文档不需要密钥库对象条目和用户注册表设置。

    以下 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" />
         例如,For example, setting
      the following configuration in the server.xml makes the public REST API
      documentation available with GET
      http://host:http_port/myAPI/docs and
      http://host:http_port/myAPI/explorer:</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.1</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 部分合并。

      还可以使用此方法来绕过注释局限性,例如,显示的安全性定义。例如,META-INF/stub 中的以下 swagger.json 允许注释引用这些定义:

      {
        "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。

      页面上的过滤器输入框允许使用上下文根的逗号分隔列表来过滤内容。

    • [17.0.0.1 and later]使用其他端点来显示公用 REST 文档。

      与先前提及的端点不同,访问这些端点不需要密钥库服务对象条目,也不需要用户注册表设置。但是,可以设置密钥库服务对象条目以通过 HTTPS 访问端点。

      缺省情况下,为服务器提供了两个端点:
      • GET http://host:http_port/api/docs
      • GET http://host:http_port/api/explorer

      您可以在 server.xml 文件中更改具有 publicURL 属性的公共端点的 URL。例如,在 server.xml 中设置以下配置可使公共 RESTAPI 文档可用于 GET http://host:http_port/myAPI/docshttp://host:http_port/myAPI/explorer

      <apiDiscovery publicURL="myAPI" />

      缺省情况下,会在公共 REST API 文档中显示已部署 Web 应用程序添加的所有 REST API 端点,但是不包含诸如 JMX REST 连接器 REST API 的内部服务器端点。您可以针对 Web 模块设置 public="false" 属性,以便不显示该模块所显示的 REST API。例如,将以下配置添加到 server.xml 会导致 Web 模块不会在公共 REST API 文档中显示 REST API。

      <apiDiscovery publicURL="myAPI">
         <webModuleDoc contextRoot="/22ExampleServlet" public="false" />
      </apiDiscovery>
    • [17.0.0.1 and later]使用 server.xml 文件中的 swaggerDefinition 属性,覆盖 /docs 端点提供的 Swagger 2.0 文档中一些字段

      您可以使用 swaggerDefinition 指定包含要覆盖的字段的 JSON 或 YAML Swagger 片段。可以覆盖 infoschemesconsumesproducesexternalDocs 字段。

    启用 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 发现是否已启用以及客户机可以在何处访问该功能部件。

示例

您可以在 OpenAPI 接口中以及 WASdev Web 站点上找到有关“REST API 发现”的更多信息。

提供了语音讲解的 IBM MediaCenter Flash 视频 观看:IBM MediaCenter 上的 IBM WebSphere Application Server Liberty API 发现视频提供了演示视频的示例和链接。(V8.5.5.9)


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

文件名:twlp_api_discovery.html