投稿者

インターシステムズジャパン

TEAM

記事 Toshihiko Minamoto · 5月 13 7m read

OpenAPI 2.0仕様を記述する

#InterSystems IRIS #API #InterSystems API Manager (IAM) #REST API

REST API（Representational State Transferアプリケーションプログラミングインターフェース）は、GET、POST、PUT、DELETEなどのHTTPメソッドを使用してウェブアプリケーション間で通信するための標準化された方法です。リソースを中心に設計されており、リソースにはユーザーやファイルなどあらゆるものが含まれます。各リソースは一意のURLで識別され、これらのリソースのやり取りはステートレスです。クライアントからサーバーへの各リクエストには、リクエストを理解して処理するために必要なすべての情報が含まれている必要があります。このステートレス性と標準的なHTTPメソッドの使用により、REST APIは高度にスケーラブルで理解しやすく、さまざまなシステムとの統合も簡単です。 RESTの原則に従うことで、開発者は一貫性があり、使いやすく、幅広いタスクに対応できるAPIを作成できます。

InterSystemsは、さまざまなツールと技術でREST API開発をサポートします。この記事シリーズでは、私自身が特にお勧めするものを取り上げます。記事は以下のように分類されています。

OpenAPI 2.0仕様の記述方法
OpenAPI 2.0仕様を使用したREST APIのドキュメント化および開発。
REST APIの呼び出しに対応するIRIS本番環境パイプラインの開発。

この記事シリーズにある手順や指示に従うには、以下の環境を事前に準備しておく必要があります。

InterSystems IRIS for Health
開発者ポータルがデプロイされ有効になっているInterSystems IAM。
Postmanまたはその他のAPIテストソフトウェア。

クリニックの予約管理のためにワークフローを開発していると想定しましょう。予約リソースとそのためのGET、POST、PUTメソッドの開発方法に焦点を置きます。同じ手順でDELETEメソッドを開発することも可能ですが、個人的に好まないためここでは行いません。

最初に、アプリケーションAPIのOpenAPI 2.0仕様を作成することから始める必要があります。このタスクではSwagger Editorを使用してYAML形式で開発し、後で仕様ファイルをJSONに変換します。その後、IRIS API管理ツールを使用してJSONファイルを使用できます。オンラインのSwagger Editorを無料で使用するか、こちらからコンテナをダウンロードしてローカルでデプロイすることも可能です。

OpenAPI仕様を作成する際、私はファイルを3つのセクションに分けて考えます。イントロセクションは、説明情報を記述します。説明、ライセンス、さまざまなエンドポイントを分類するタグ、ホストとベースURLを組み合わせたURLなど、アプリケーションの性質を説明するフィールドが含まれます。必要に応じて、スキーマやセキュリティ定義など、動作の制約も含まれます。

以下のコードブロックには、以降で参照するサンプルのイントロセクションが含まれています。これをSwagger Editorに貼り付けると、APIドキュメントの基礎が形成されていくのが分かります。

swagger: "2.0"
info:
  description: "This is a sample server to be as an example Clinic server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io). For this sample, you can use the api key `special-key` or Basic Auth user `Basic` with password `Basic` to test the authorization filters."
  version: "1.0.0"
  title: "Clinic Management"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "raef.youssef@intersystems.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "apigatewaydns"
basePath: "/clinic"
tags:
- name: "Scheduling"
  description: "Everything about your Pets"
  externalDocs:
    description: "Find out more"
    url: "http://intersystems.com"
schemes:
- "http"
- "https"
securityDefinitions:
  BasicAuth:
    type: "basic"
    name: "Basic"
  api_key:
    type: "apiKey"
    name: "api_key"
    in: "header"

仕様ファイルの2つ目のセクションは本文です。このセクションでは、さまざまなパス（エンドポイント）とそれぞれで利用できるメソッドを記述します。このデモの目的のために、“/appointment” エンドポイントの仕様のみを作成します。以下はその仕様のテキストです。


paths:
  /appointment:
    get:
      tags:
        - Scheduling
      summary: "Fetches an existing appointment details"
      security:
      - Basic: []
      description: "Fetches an existing appointment details by providing its ID"
      operationId: "getAppointmentByID"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "id"
        type: "integer"
        format: "int64"
        description: "ID of the appointment sought"
        required: true
      responses:
        '200':
          description: successful operation
#          schema:
#            $ref: '#/definitions/appointment'
    post:
      tags:
        - Scheduling
      summary: ""
      security:
      - api_key: []
      description: ""
      operationId: "postAppointment"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - in: "formData"
        name: "Date"
        type: "string"
        format: "date-time"
        description: ""
        required: true
      - in: "formData"
        name: "duration"
        type: "integer"
        format: "int64"
        description: "number of half hour slots of the appointment duration"
        required: true
      responses:
        '200':
          description: successful operation
        '405':
          description: Time not available
    put:
      tags:
        - Scheduling
      summary: ""
      security:
      - BasicAuth: []
      description: ""
      operationId: "updateAppointment"
      consumes:
      - "application/json"
      - "application/xml"
      produces:
      - "application/json"
      - "application/xml"
      parameters:
      - in: "query"
        name: "id"
        type: "integer"
        format: "int64"
        description: "ID of the appointment sought"
        required: true
      - in: "body"
        name: "body"
        description: ""
        required: true
#        schema:
#          $ref: "#/definitions/appointment"
      responses:
        '200':
          description: successful operation
        '405' :
          description: Time not available
        '406' :
          description: Appointment Not Found

パスセクションでの注意点がいくつかあります。まず、各メソッドに対して異なる認証メカニズムを割り当てることができます。 “OperationID” は、それぞれのメソッド呼び出しを処理するバックエンドプロセスの名前を指定するためのフィールドです。さらに、リクエストのJSON本文と応答のためのスキーマを定義できます。まだ定義されていないので、貼り付けたときにエラーにならないように、ここではコメントアウトしてあります。最後に、カスタムの応答コードとメッセージを定義できます。

最後のセクションでは、さまざまなメッセージのスキーマを定義します。この例では、appointmentスキーマを作成し、予約ID、日付、所要時間、サービス提供者名を含めます。 YAML定義のテキストは次のとおりです。エディターに以下を貼り付けた後に、スキーマ定義が参照されている行のコメントを解除できます。

definitions:
    appointment:
        type: "object"
        properties:
            id:
                type: "integer"
                format: "int64"
            Provider:
                type: "string"
                format: "string"
            Date:
                type: "string"
                format: "date-time"
            Duration:
                type: "integer"
                format: "int64"

以上で、このシリーズのこの部分は終了です。シリーズの後の部分でこの仕様を使用します。近日公開予定ですので、お楽しみに！ OpenAPI 2.0仕様の開発の詳細については、こちらのドキュメントを参照してください。

元の記事へさんが書いた @Raef Youssef

ディスカッション (0)0

続けるにはログインするか新規登録を行ってください

返信を追加する