OpenAPI Suite - パート 1

git clone git@github.com:lscalese/openapi-suite.git
cd openapi-suite
docker-compose up -d

Iris の起動にエラーがある場合は、おそらく iris-main.log の権限の問題と思われます。

touch iris-main.log && chmod 777 iris-main.log

注意: irisowner ユーザーに RW 権限を追加するだけで十分なはずです。

Set features("simpleHttpClientOnly") = 1Set sc = ##class(dc.openapi.client.Spec).generateApp("petstoreclient", "https://petstore3.swagger.io/api/v3/openapi.json", .features)

Set messageRequest = ##class(petstoreclient.requests.addPet).%New()
Set messageRequest.%ContentType = "application/json"Do messageRequest.PetNewObject().%JSONImport({"id":456,"name":"Mittens","photoUrls":["https://static.wikia.nocookie.net/disney/images/c/cb/Profile_-_Mittens.jpg/revision/latest?cb=20200709180903"],"status":"available"})
Set httpClient = ##class(petstoreclient.HttpClient).%New("https://petstore3.swagger.io/api/v3","DefaultSSL")
; MessageResponse will be an instance of petstoreclient.responses.addPetSet sc = httpClient.addPet(messageRequest, .messageResponse)
If$$$ISERR(sc) Do$SYSTEM.Status.DisplayError(sc) Quit sc
Write !,"Http Status code : ", messageResponse.httpStatusCode,!
Do messageResponse.Pet.%JSONExport()

<div class="spoiler-content" style="">
  <pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">Class</span> petstoreclient.HttpClient <span class="hljs-keyword">Extends</span> <span class="hljs-built_in">%RegisteredObject</span> [ ProcedureBlock ]

  <p>
     
  </p>
  
  <pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">Class</span> petstoreclient.requests.addPet <span class="hljs-keyword">Extends</span> <span class="hljs-built_in">%RegisteredObject</span> [ ProcedureBlock ]

  <p>
     
  </p>
  
  <pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">Class</span> petstoreclient.responses.addPet <span class="hljs-keyword">Extends</span> petstoreclient.responses.GenericResponse [ ProcedureBlock ]

  <p>
     
  </p>
</div>

HTTP クライアントのプロダクション

Set sc = ##class(dc.openapi.client.Spec).generateApp("petstoreproduction", "https://petstore3.swagger.io/api/v3/openapi.json")

最初の引数は、単純な HTTP クライアントのコード生成をテストする場合のパッケージ名であるため、クライアントプロファクションの場合は必ず別のパッケージ名を使用してください。  2 つ目と 3 つ目も HTTP クライアントと同じルールが適用されます。

Do##class(Ens.Director).StartProduction("petstoreproduction.Production")

以下は、「addPet」サービスを使用する例ですが、今回は生成されたプロダクションを使用します。

Set messageRequest = ##class(petstoreproduction.requests.addPet).%New()
Set messageRequest.%ContentType = "application/json"Do messageRequest.PetNewObject().%JSONImport({"id":123,"name":"Kitty Galore","photoUrls":["https://www.tippett.com/wp-content/uploads/2017/01/ca2DC049.130.1264.jpg"],"status":"pending"})
; MessageResponse will be an instance of petstoreclient.responses.addPetSet sc = ##class(petstoreproduction.Utils).invokeHostSync("petstoreproduction.bp.SyncProcess", messageRequest, "petstoreproduction.bs.ProxyService", , .messageResponse)
Write !, "Take a look in visual trace (management portal)"If$$$ISERR(sc) Do$SYSTEM.Status.DisplayError(sc)
Write !,"Http Status code : ", messageResponse.httpStatusCode,!
Do messageResponse.Pet.%JSONExport()

次に、視覚的なトレースを開いて詳細を確認します。 

packages モデル、リクエスト、およびレスポンスに生成されたクラスは、単純な HTTP クライアント用に生成されるコードと非常によく似ています。  パッケージリクエストのクラスは Ens.Request を継承し、パッケージレスポンスのクラスは Ens.Response を継承します。  ビジネスオペレーションのデフォルトの実装は非常に単純です。以下のスニペットをご覧ください。 

Class petstoreproduction.bo.Operation Extends Ens.BusinessOperation [ ProcedureBlock ]
{

Parameter ADAPTER = "EnsLib.HTTP.OutboundAdapter";Property Adapter As EnsLib.HTTP.OutboundAdapter;/// Implement operationId : addPet/// post /pet
Method addPet(requestMessage As petstoreproduction.requests.addPet, Output responseMessage As petstoreproduction.responses.addPet) As%Status
{
    Set sc = $$$OK, pHttpRequestIn = ##class(%Net.HttpRequest).%New(), responseMessage = ##class(petstoreproduction.responses.addPet).%New()
    $$$QuitOnError(requestMessage.LoadHttpRequestObject(pHttpRequestIn))
    $$$QuitOnError(..Adapter.SendFormDataArray(.pHttpResponse, "post", pHttpRequestIn, , , ..Adapter.URL_requestMessage.%URL))
    $$$QuitOnError(responseMessage.LoadFromResponse(pHttpResponse, "addPet"))
    Quit sc
}
...
}
}

HTTP サーバーサイド REST アプリケーション

Set sc = ##class(dc.openapi.server.ServerAppGenerator).Generate("petstoreserver", "https://petstore3.swagger.io/api/v3/openapi.json", "/petstore/api")

最初の引数は、クラスを生成するパッケージ名です。  2 つ目は HTTP クライアントと同じルールが適用されます。  3 つ目の引数は必須ではありませんが、使用されている場合、Web アプリケーションが指定された名前で作成されます（有効な Web アプリケーション名を指定することに注意してください）。

Class petstoreserver.disp Extends%CSP.REST [ ProcedureBlock ]
{
Parameter CHARSET = "utf-8";Parameter CONVERTINPUTSTREAM = 1;Parameter IgnoreWrites = 1;Parameter SpecificationClass = "petstoreserver.Spec";/// Process request post /petClassMethod addPet() As%Status
{
Set sc = $$$OKTry{
Set acceptedMedia = $ListFromString("application/json,application/xml,application/x-www-form-urlencoded")
If '$ListFind(acceptedMedia,$$$LOWER(%request.ContentType)) {
Do##class(%REST.Impl).%ReportRESTError(..#HTTP415UNSUPPORTEDMEDIATYPE,$$$ERROR($$$RESTContentType,%request.ContentType)) Quit
}
Do##class(%REST.Impl).%SetContentType($Get(%request.CgiEnvs("HTTP_ACCEPT")))
If '##class(%REST.Impl).%CheckAccepts("application/xml,application/json") Do##class(%REST.Impl).%ReportRESTError(..#HTTP406NOTACCEPTABLE,$$$ERROR($$$RESTBadAccepts)) QuitIf '$isobject(%request.Content) Do##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR($$$RESTRequired,"body")) QuitSet requestMessage = ##class(petstoreserver.requests.addPet).%New()
Do requestMessage.LoadFromRequest(%request)
Set scValidateRequest = requestMessage.RequestValidate()
If$$$ISERR(scValidateRequest) Do##class(%REST.Impl).%ReportRESTError(..#HTTP400BADREQUEST,$$$ERROR(5001,"Invalid requestMessage object.")) QuitSet response = ##class(petstoreserver.impl).addPet(requestMessage)
Do##class(petstoreserver.impl).%WriteResponse(response)
} Catch(ex) {
Do##class(%REST.Impl).%ReportRESTError(..#HTTP500INTERNALSERVERERROR,ex.AsStatus(),$parameter("petstoreserver.impl","ExposeServerExceptions"))
}
Quit sc
}
...
}

ご覧のとおり、dispatch クラスは実装メソッドを呼び出す前に「LoadFromRequest」と「RequestValidate」を呼び出しています。  これらのメソッドにはデフォルトの実装がありますが、コードジェネレーターはすべてのケースに対応できません。  現時点では、「query」、「headers」、「path」、およびコンテンツタイプが「application/json」、「application/octet-stream」、または「multipart/form-data」である body で最も一般的なケースがパラメーターとして自動的に処理されます。  開発者は、必要に応じて実装をチェック/完了する必要があります（未対応のケースについては、デフォルトでは、コードジェネレーターは $$$ThrowStatus($$$ERROR($$$NotImplemented)) を設定します）。

  <td>
    タイプ
  </td>
  
  <td>
    説明
  </td>
</tr>

<tr>
  <td>
    petstoreclient.model petstoreproduction.model
  </td>
  
  <td>
    クライアントサイドとサーバーサイド
  </td>
  
  <td>
    すべてのモデルが含まれます。  これらのクラスは、JSON から簡単にオブジェクトを読み込めるように %JSON.Adaptor を拡張します。   プロダクションが生成されると、これらのクラスは %Persistent も拡張します。
  </td>
</tr>

<tr>
  <td>
    petstoreclient.requests   petstoreproduction.requests
  </td>
  
  <td>
    クライアントサイドとサーバーサイド
  </td>
  
  <td>
    %Net.HttpRequest を簡単に初期化するために使用されるオブジェクト。  仕様にはオペレーションごとのクラスが定義されています。プロダクションが生成される場合、これらのクラスは Ens.Request を拡張します。 注意: このクラスの実装は、生成対象がサーバーサイドであるかクライアントサービスであるかによって異なります。  クライアントサイドの場合、すべてのクラスには「LoadHttpRequestObject」メソッドが含まれるため、このクラスプロパティから「%Net.HttpRequest」を読み込むことができます。 クラスがサーバーサイドを対象に生成される場合、「%request」オブジェクトからインスタンスを読み込むために、各クラスに「LoadFromRequest」メソッドが含まれています。
  </td>
</tr>

<tr>
  <td>
    petstoreclient.responses petstoreproduction.responses
  </td>
  
  <td>
    クライアントサイドとサーバーサイド
  </td>
  
  <td>
    petstoreclient.requests の 逆です。  %Net.HttpRequest のレスポンスを処理できます。プロダクションが生成される場合、これらのクラスは Ens.Response を拡張します。
  </td>
</tr>

<tr>
  <td>
    petstoreclient.HttpClient
  </td>
  
  <td>
    クライアントサイド
  </td>
  
  <td>
    HTTP リクエストを実行するためのすべてのメソッドが含まれます。OpenAPI 仕様で定義されるオペレーションごとに 1 つのメソッドがあります。
  </td>
</tr>

<tr>
  <td>
    petstoreproduction. bo.Operation
  </td>
  
  <td>
    クライアントサイド
  </td>
  
  <td>
    オペレーションクラスには、OpenAPI 仕様で定義されたオペレーションごとに 1 つのメソッドがあります。
  </td>
</tr>

<tr>
  <td>
    petstoreproduction.bp
  </td>
  
  <td>
    クライアントサイド
  </td>
  
  <td>
    同期と非同期の 2 つのデフォルトのビジネスプロセスが定義されています。
  </td>
</tr>

<tr>
  <td>
    petstoreproduction.bs
  </td>
  
  <td>
    クライアントサイド
  </td>
  
  <td>
    実装するすべての空のビジネスサービスが含まれます。
  </td>
</tr>

<tr>
  <td>
    petstoreproduction.Production
  </td>
  
  <td>
    クライアントサイド
  </td>
  
  <td>
    プロダクション構成の設定。
  </td>
</tr>

<tr>
  <td>
    petstoreserver.disp
  </td>
  
  <td>
    サーバーサイド
  </td>
  
  <td>
    クラス dispatch %CSP.REST
  </td>
</tr>

<tr>
  <td>
    petstoreserver.Spec
  </td>
  
  <td>
    サーバーサイド
  </td>
  
  <td>
    このクラスには、XData ブロックに OpenAPI 仕様が含まれています。
  </td>
</tr>

<tr>
  <td>
    petstoreserver.impl
  </td>
  
  <td>
    サーバーサイド
  </td>
  
  <td>
    これには、OpenAPI 仕様で定義されたオペレーションに関連するすべての空のメソッドが含まれています。  これが、開発者がサービスを実装する必要のあるクラス（%REST.Impl を拡張）です。
  </td>
</tr>