OpenAPI : API仕様の設計方法

OpenAPIはJSONまたはYAMLベースの仕様書です.それはあなたのAPIの詳細な仕様を設計するのに役立ちます:エンドポイント、使用するペイロード、期待されるHTMLステータスコード.このような仕様では、さまざまなOpenAPIツールを使用する機会を提供します.APIの可視化、自動リクエストの実行、コードの検証やコード生成を行います.
本稿はOpenAPI仕様書の作成について説明する.この努力の実行例は、私の内部APIですlighthouse SAAS . 一般的なメタデータ、APIエンドポイント、および応答/リクエストデータの構造をどのように指定できるかを見る.
この記事はもとでmy blog .

OpenAPI構築ブロック
OpenAPI仕様は次の要素から成ります.

メタデータ:このセクションでは、APIの仕様そのものについての情報を、バージョン、タイトル、作者、更なるリンクのようにエンコードします

サーバー:あなたが記述しているAPIを提供するサーバのリストは、いくつかのツールが生成するために使用されますcurl LIVEを使用してAPIを問い合わせるステートメント

エンドポイント:この情報を持つ複雑なオブジェクトとして記述されたAPIの具体的な終点

スキーマ/定義:すべての構造化されたデータオブジェクトは、リクエストで使用されるか、または応答において返されます.このセクションで定義され、次に、仕様の範囲内の他の部分から参照されることができます

これらはビルディングブロックです.いくつかのニュアンスは、OpenAPIの異なるバージョンが付属しています:以前はswaggerと呼ばれ、多くの古いプロジェクトはまだこのバージョンを使用します.この記事はOpenAPIフォーマットを独占しています.

例:灯台API
灯台は、Webページをスキャンし、どのように良いSEO、パフォーマンスとベストプラクティスの条件でスコアを参照してくださいサービスです.ここでスキャナを使用できます.https://lighthouse.admantium.com/ .
スキャナは2つの主要なエンドポイントを提供します/scan , ここでurl クエリパラメータが渡され、/api/jobs 通過することによってuuid クエリパラメータ.これらの2つのエンドポイント、パラメーター、応答コード、および戻り値/オブジェクトを指定する方法を参照します.

オープンハウスのためのオープンAPI宣言
APIを定義するための現在のOpenAPIバージョン3.0とYAMLデータ形式を使用します.

情報とリストサーバー
ドキュメントの冒頭では、仕様に関する重要なメタデータ、あなたが使用しているAPIバージョン、バージョン、タイトルなどに関する重要なメタデータを提供しています.

openapi: 3.0.0
info:
  version: 1.0
  title: Lighthouse API

servers:
  - url: https://lighthouse.admantium.com/

また、APIをホストしているサーバーの一覧を追加することもできます.この情報は、APIを直接呼び出すコードを生成するためのツールや、curl エンドポイントを直接呼び出すコマンド.

servers:
  - url: https://lighthouse.admantium.com/

スキャナ終点
スキャナエンドポイントはHTTPを受け入れるGET 要求と要求url パラメータこれは以下の3つのステータスコードに従います.200 , 400 and 429 . 次の手順を実行します

エンドポイントを定義しますpaths

それぞれのパスは少なくとも1つのHTTPメソッドを持っています:get , post , put , option , query , delete

それぞれのメソッドはdescription , parameters and responses

responses 少なくとも1つのステータスコードを返します.

スキャナのエンドポイント記述の最初のバージョンは次のようになります.

paths:
  /scan:
    get:
      description: Initiate a webpage scan
      parameters:
        ...
      responses:
        200:
          ...
        400:
          ...
        429:
          ...

次にパラメータを詳細に説明します.まず、パラメータを定義するname . 次に、パラメータがどこにあるかを定義しますin -手掛かりでquery , またはbody . The schema 定義type .

paths:
  /scan:
    get:
      description: Initiate a webpage scan
      parameters:
        - name: url
          in: query
          schema:
            type: string

そして最後に、我々は応答についての詳細を与える.ステータスコードの後にdescription とcontent . 最初の内容はmime-type , これは、application/json and text/html . JSONの場合、完全なスキーマ定義の形で詳細を提供することができます.

paths:
  /scan:
    get:
      # ...
      responses:
        200:
          description: Webpage scan is accepted and will be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultError'
        429:
          description: Scan requests can not be accepted, all workers are occupied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'

ジョブ終点
アプリケーションの別のエンドポイントは、スキャンジョブのステータスをチェックする機能を提供します.このエンドポイントは/api/jobs , そして、それはuuid クエリパラメータ.

/api/jobs:
    get:
      description: Get the job status for the provided `uuid`
      parameters:
        - name: uuid
          in: query
          schema:
            type: string
      responses:

応答は200 完了した場合は202 進行中の仕事のために.409 、エラーが発生した場合に400 を返します.どのようなステータスコード、MIMEタイプは常にapplication/json . 具体的な応答ペイロードは、以前と同様に、別のオブジェクトとして詳細です.

responses:
  200:
    description: 'JOB status: finished'
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/JobResponse'
  202:
    description: 'JOB status: started'
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/JobResponse'
  400:
    description: Invalid request
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/DefaultError'
  409:
    description: 'JOB status: error'
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/JobResponse'

リクエストまたは応答JSONペイロードデータ構造の定義
に戻る/scan エンドポイントとその結果.MIMEタイプ定義の下でapplication/json , 私たちは$ref 定義は、既存の仕様へのポインタです.この特定の例では、ポインタは#/components/schemas/ScanResponse , このファイルではcomponents/schemas , 使用するScanResponse データ型".

responses:
  200:
    description: Webpage scan is accepted and will be processed
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ScanResponse'

このスキーマ定義の詳細を見ることができます.名前から始まるScanResponse , とtype is object . このオブジェクトはproperties : エーstring msg , エーinteger code , とstring uuid . さらに、個々の属性の構造を指定する正規表現を定義することもできます.

components:
  schemas:
    ScanResponse:
      type: object
      properties:
        msg:
          type: string
        code:
          type: integer
        uuid:
          type: string

の定義JobResponse 固有の構造を持つため、DataTypeはより複雑ですmsg , code and job , を指定します.uuid , domain , status and record . この複雑さはOpenAPI仕様で単純化されますjob 宣言.結果を以下に示します.

JobResponse:
  type: object
  properties:
    msg:
      type: string
    code:
      type: integer
    job:
      type: object
      properties:
        uuid:
          type: string
        domain:
          type: string
        status:
          type: string
        record:
          type: boolean

完全な例
あなたは、灯台API仕様の完全な例を見ることができますhere .

概要
OpenAPIでは、詳細にAPIを指定できます.エンドポイント、パラメーター、リクエスト/レスポンスオブジェクト.簡潔な宣言言語では、これらの要素を定義します.仕様モデルは、さまざまなツールで使用することができます:ドキュメントビューア、バリデータ、さらにはコードジェネレータ.次の記事では、このツールチェーンについての詳細を読むことができます.