REST easy with kbmMW #20 – OpenAPI and Swagger UI

即将推出的kbmMW更新不仅是一些bug修正，同时将包含一个新的主要功能：客户端存根生成器框架。

那什么是客户端存根生成器框架呢？

他是一个基于kbmMW smart services，可以生成由各种类型的客户端直接使用的代码，以访问基于kbmMW应用服务器的HTTP smart services。(什么是HTTP Smart Service呢？可参考洞主写的文章：kbmmw 的HTTP Smart Service入门)

 当前，kbmMW已经实现智能客户端（smart client）功能，通过这个功能，非常容易实现客户端来访问smart services中的功能。由于智能客户端依赖于后期绑定，所以开发者无法通过IDE及编译器的帮助，来获得有关参数及其类型。因此，编译器还需要生成一些代码，为IDE及编译器，来解释服务端发布的函数及方法。

上面这个问题，正是客户端存根生成器要解决的问题，但是，本文不会讨论如何为智能服务生成Delphi客户端存根，因为尽管已经做了这方面的准备工作，但这个特定功能可能不会在即将发布的版本中完整实现。相反，我将介绍利用存根生成器框架来实现另一个更复杂的代码集，满足REST世界中的典型需求。一年多前，当我咨询大公司做Java代码时，认识到了这一点。

在Java世界中，使用当时被称为Swagger的东西来记录REST接口，这是一个事实上的标准。后来它被重命名为OpenAPI，现在得到了绝大多数支持REST的开发者的认可和支持。

OpenAPI提供了REST接口的描述，可以用于文档，也可以用于为各种开发环境自动生成（存根）代码，使这些环境可以轻松利用通过REST接口发布的功能。（Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。）

您可以在此处阅读有关OpenAPI的更多信息：

 

OpenAPI不仅成为事实上的标准，还生成了可用于生成，编辑，查看和测试REST接口描述的各种工具（通常称为Swagger文件）。

其中一个工具是Swagger-UI（用户界面），它由Javascript和HTML组成，可以由Web服务器提供，为服务器中公开的REST接口提供简单易用的用户界面。

kbmMW现在完全支持所有这些。

让我们简单地开始使用Swagger-UI展示kbmMW SimpleInvocation演示服务器的REST接口是什么样的：

在左侧，可以看到公开的REST接口的OpenAPI声明，右侧可以看到用户友好的界面，通过简单的按钮点击可以调用这些界面。填充参数甚至REST方法也很容易。

如果我向右滚动到AddNumbers方法，然后单击该栏，它会打开其他信息，以及一个让我们尝试REST调用的按钮。

 

这非常酷!

那么我们如何使支持REST的应用服务器启用OpenAPI呢？

这真的很容易。

要返回REST服务的OpenAPI规范，我们只需在Unit2中向服务添加另一个REST公开方法。

     [kbmMW_Rest('method:get, path: "api", responseMimeType:"application/x-yaml"')]
     function OpenAPI:string;

这可以根据您的喜好来命名方法及其REST路径，但我们应该提供正确的responseMimeType。OpenAPI描述的标准用YAML表示，幸运的是kbmMW完全支持。它也允许在JSON中生成OpenAPI描述，但它更像是一种与不支持YAML的系统兼容的方法。所以在这个例子中，我们在responseMimeType中指定响应类型为YAML。

// Return OpenAPI specification.
function TkbmMWCustomService2.OpenAPI:string;
begin
     // Return OpenAPI specification for all REST methods in this service
     // as YAML. Add the ASettings value: 'json:true' to return the specification
     // as JSON.
     // Add 'servers: [ "url1", "url2",.. "urln" ]' to ASettings if you want to
     // embed server location information in the specification.
     // Add 'inline:true' to inline object definitions instead of using $ref.
     // The example in the next line utilize the configuration framework to make
     // the setting easily configurable.
     Result:=TkbmMWSmartOpenAPIStubGenerator.GenerateOpenAPI('',self,'inline:$(OpenAPI.inline=false)');
end;

OpenAPI函数的实现代码非常简单，只调用OpenAPI存根生成器的GenerateOpenAPI方法，服务为“OpenAPI'ified”，并可选择设置字符串。设置字符串可以为空，在这个示例中，设置字符串包含值为：

inlinei:$(OpenAPI.inline=false)

原因是有两种有效的方法可以为REST接口生成OpenAPI规范，这些接口可以内联或通过引用获取或返回对象。

内联意味着每个对象都会详细解释它可以在REST调用的所有描述中使用的每个位置，而引用意味着在需要时描述和引用OpenAPI样式组件（对象）。引用是默认值。但是在示例代码中，我选择在kbmMW配置框架的帮助下对其进行配置。我们可以编写：inline：false或inline：true，但是样本会询问配置OpenAPI.inline值的当前值，该值可以是true或false。如果没有找到这样的值，kbmMW将使用默认值false（如=后面所示）。

也可以指定JSON是首选。这只需要将json：true添加到设置字符串，如下所示：

inline:$(OpenAPI.inline=false), json:true

显然，这也可以像内联一样进行配置。

但是我们保持原样，因此OpenAPI函数的输出将是对服务中REST方法的YAML格式化OpenAPI描述。

因此，如果我们使用浏览器打开URL:http://localhost:888/myserver/api，我们将获得完整的OpenAPI描述：

openapi: "3.0.0"
info: 
  title: SMARTDEMO
  description: "HTTP smart service supp. FastCGI"
  version: "1"
paths: 
  /myserver/api: 
    get: 
      operationId: get_myserver_api
      responses: 
        "200": 
          content: 
            application/x-yaml: 
              schema: 
                type: string
          description: "Success response"
  /myserver/helloworld: 
    get: 
      operationId: get_myserver_helloworld
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/now1: 
    get: 
      operationId: get_myserver_now1
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
                format: date-time
          description: "Success response"
  /myserver/now2: 
    get: 
      operationId: get_myserver_now2
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: number
                format: double
          description: "Success response"
  /myserver/echostring/{AString}: 
    get: 
      operationId: get_myserver_echostring__AString_
      parameters: 
        - 
          in: path
          name: AString
          required: true
          schema: 
            type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/myechostring/{AString}: 
    get: 
      operationId: get_myserver_myechostring__AString_
      parameters: 
        - 
          in: path
          name: AString
          required: true
          schema: 
            type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echourl: 
    get: 
      operationId: get_myserver_echourl
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echoheader: 
    get: 
      operationId: get_myserver_echoheader
      parameters: 
        - 
          in: header
          name: Accept
          required: true
          schema: 
            type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echoanyheader/{AHeaderName}: 
    get: 
      operationId: get_myserver_echoanyheader__AHeaderName_
      parameters: 
        - 
          in: path
          name: AHeaderName
          required: true
          schema: 
            type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echocookie: 
    get: 
      operationId: get_myserver_echocookie
      parameters: 
        - 
          in: cookie
          name: MyCookie
          required: true
          schema: 
            type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echoreversedstring: 
    post: 
      operationId: post_myserver_echoreversedstring
      requestBody: 
        required: true
        content: 
          text/plain: 
            schema: 
              type: string
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /myserver/echobytes: 
    post: 
      operationId: post_myserver_echobytes
      requestBody: 
        required: true
        content: 
          text/plain: 
            schema: 
              type: string
              format: byte
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
                format: byte
          description: "Success response"
  /myserver/echoreversedconfigstring: 
    get: 
      operationId: get_myserver_echoreversedconfigstring
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: string
          description: "Success response"
  /someabspath/addnumbers: 
    get: 
      summary: "Adds two numbers and returns result"
      operationId: add_numbers
      parameters: 
        - 
          in: query
          name: arg1
          required: true
          description: "First numeric argument"
          schema: 
            type: integer
            format: int32
        - 
          in: query
          name: arg2
          required: true
          description: "Second numeric argument"
          schema: 
            type: integer
            format: int32
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: integer
                format: int32
          description: "The result of the added numbers"
  /myserver/storeperson: 
    post: 
      operationId: post_myserver_storeperson
      requestBody: 
        required: true
        content: 
          text/plain: 
            schema: 
              "$ref": "#/components/schemas/person"
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: integer
                format: int32
          description: "Success response"
  /myserver/getperson/{id}: 
    get: 
      operationId: get_myserver_getperson__id_
      parameters: 
        - 
          in: path
          name: id
          required: true
          schema: 
            type: integer
            format: int32
      responses: 
        "200": 
          content: 
            application/json: 
              schema: 
                "$ref": "#/components/schemas/person"
          description: "Success response"
  /myserver/getpersons: 
    get: 
      operationId: get_myserver_getpersons
      responses: 
        "200": 
          content: 
            application/json: 
              schema: 
                type: array
                items: 
                  "$ref": "#/components/schemas/person"
          description: "Success response"
components: 
  schemas: 
    person: 
      properties: 
        Name: 
          type: string
        Address: 
          type: string
        Age: 
          type: integer
          format: int32
      type: object
      title: person

如果你愿意，可以随意学习。您可能会注意到有几个地方，有设施可以添加摘要和说明。例如，检查addnumbers调用：

  /someabspath/addnumbers: 
    get: 
      summary: "Adds two numbers and returns result"
      operationId: add_numbers
      parameters: 
        - 
          in: query
          name: arg1
          required: true
          description: "First numeric argument"
          schema: 
            type: integer
            format: int32
        - 
          in: query
          name: arg2
          required: true
          description: "Second numeric argument"
          schema: 
            type: integer
            format: int32
      responses: 
        "200": 
          content: 
            text/plain: 
              schema: 
                type: integer
                format: int32
          description: "The result of the added numbers"

摘要和描述来自哪里？

看一下Unit2.pas中AddNumbers函数的定义，很明显：

     // Add two numbers.
     // It can be called from regular clients, smart clients
     // and REST clients.
     // It can be called from a browser like this:
     // http://.../someabspath/addnumbers?arg1=10&arg2=20
     [kbmMW_Method]
     [kbmMW_Rest('method:get, path: "/someabspath/addnumbers", '+
                 'id:"add_numbers", '+
                 'summary:"Adds two numbers and returns result", '+
                 'resultDescription:"The result of the added numbers"')]
     function AddNumbers([kbmMW_Rest('value: "$arg1", required: true, description:"First numeric argument"')] const AValue1:integer;
                         [kbmMW_Rest('value: "$arg2", required: true, description:"Second numeric argument"')] const AValue2:integer;
                         [kbmMW_Arg(mwatRemoteLocation)] const ARemoteLocation:string):integer;

kbmMW_Rest属性中甚至有一个id值。OpenAPI要求每个REST路径必须具有唯一ID。kbmMW将自动尝试生成一个，但您可以通过id语法选择自己的ID名称，如上所示。id，summary，description和resultDescription都是（以kbmMW为单位）全部可选。如果OpenAPI需要描述性值且未给出任何值，则kbmMW提供默认值。

所以现在我们可以生成有效的OpenAPI描述。我们如何让我们的基于kbmMW的应用服务器使用Swagger-UI呈现它们

因为kbmMW可以充当Web服务器，所以这实际上也很容易。我们只需将TkbmMWFilePool实例添加到主窗体（Unit1）并将服务数据模块（Unit2）的FilePool属性设置为指向它。

 

现在，kbmMW将作为常规Web服务器工作，并在未找到要调用的REST函数时尝试提供文件。

在与SimpleInvocation服务器可执行文件相同的目录中，您应该创建一个名为MyServer的目录（以匹配服务），在其下面，我们添加一个api目录，两者都只是为了匹配Unit2中OpenAPI函数的逻辑路径。实际上，您不必使用此特定路径层次结构，但我已选择此类演示。

在api目录中，我们将放置从https://swagger.io/tools/swagger-ui/下载的文件

 

然后

和

您可以将dist文件夹中的所有文件逐个下载到api \ dist目录，也可以通过克隆或下载按钮下载所有文件。如果您执行稍后操作，则打开下载的zip文件并将包含内容的dist文件夹解压缩到api目录。

最后将一个名为index.html的文件添加到api目录中。您可以从以下位置复制/粘贴其内容：

<!DOCTYPE html>
<!-- HTML for static distribution bundle build -->
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Swagger Editor</title>
  <style>
  * {
    box-sizing: border-box;
  }
  body {
    font-family: Roboto,sans-serif;
    font-size: 9px;
    line-height: 1.42857143;
    color: #444;
    margin: 0px;
  }

  #swagger-editor {
    font-size: 1.3em;
  }

  .container {
    height: 100%;
    max-width: 880px;
    margin-left: auto;
    margin-right: auto;
  }

  #editor-wrapper {
    height: 100%;
    border:1em solid #000;
    border:none;
  }

  .Pane2 {
    overflow-y: scroll;
  }

  </style>
  <link href="./dist/swagger-editor.css" rel="stylesheet">
  <link rel="icon" type="image/png" href="./dist/favicon-32x32.png" sizes="32x32" />
  <link rel="icon" type="image/png" href="./dist/favicon-16x16.png" sizes="16x16" />
</head>

<body>
  <div id="swagger-editor"></div>
  <script src="./dist/swagger-editor-bundle.js"> </script>
  <script src="./dist/swagger-editor-standalone-preset.js"> </script>
  <script>
  window.onload = function() {
    // Build a system
    const editor = SwaggerEditorBundle({
      dom_id: '#swagger-editor',
      layout: 'StandaloneLayout',
      presets: [
        SwaggerEditorStandalonePreset
      ]
    })

    window.editor = editor
  }
  </script>

  <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
    <defs>
      <symbol viewBox="0 0 20 20" id="unlocked">
            <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
      </symbol>

      <symbol viewBox="0 0 20 20" id="locked">
        <path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
      </symbol>

      <symbol viewBox="0 0 20 20" id="close">
        <path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
      </symbol>

      <symbol viewBox="0 0 20 20" id="large-arrow">
        <path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
      </symbol>

      <symbol viewBox="0 0 20 20" id="large-arrow-down">
        <path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
      </symbol>


      <symbol viewBox="0 0 24 24" id="jump-to">
        <path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
      </symbol>

      <symbol viewBox="0 0 24 24" id="expand">
        <path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
      </symbol>

    </defs>
  </svg>

</body>

</html>

现在你准备摇滚了。

启动服务器。然后启动浏览器并输入：

http://localhost:888/myserver/api/index.html?url=/myserver/api

这指示kbmMW提供index.html文件，该文件反过来请求生成Swagger-UI接口所需的剩余文件。最后，我们告诉Swagger-UI从/ myserver / api URL加载OpenAPI描述（如果你记得的话，将在Unit2中调用OpenAPI函数）。

您现在应该得到类似于此博客文章开头所示的视图。

在Swagger-UI界面中，您可以为kbmMW公开的所有REST功能生成服务器骨架和客户端存根。

快乐的摇摆！！！

如果你喜欢kbmMW，请分享这个词。转发博客文章，让其他人了解该产品！

https://components4developers.blog/2018/12/31/rest-easy-with-kbmmw-20-openapi/