OpenAPIのCLIへのマッピング

我々が探検するこのポストでRestish , OpenAPIサポートを内蔵したAPIのためのCLI.どのように、それはCLAPI命令と議論にOpenAPIサービス説明から行きますか?記事を読むに見つける!

自動発見

Resexeはいくつかの異なるメカニズムを使用してOpenAPIの自動発見をサポートします.あなたは提供することができますRFC 8631 service-desc リンクリレーションRFC 5988 describedby 関係をリンクする、または提供する/openapi.yaml or /openapi.json あなたのAPIで.

リンクリレーションヘッダー

使用する場合service-desc or describedby リンクの関係は、RESPORTはOpenAPIを見つけるためにリンクに従ってください.例えば、あなたが得るならhttps://api.example.com/ 次のヘッダを返すことがあります.

Link: </path/to/openapi.yaml>; rel="service-desc"

その後、再会はhttps://api.example.com/path/to/openapi.yaml を使用して、演算、引数、フラグなどにロードします.

フォールバック機構

リンクリレーションヘッダーが存在しない場合、フォールバックメカニズムが使用されます.再会するhttps://api.example.com/openapi.yaml or https://api.example.com/openapi.json . 見つかったら、それをロードします.

CLI操作の解剖学

CLI操作はいくつかの部分からなります.

名称
説明
API
APIの短い名前は、Ristish(あなたが望む何でも)でAPIを登録するとき、構成されます.
操作
OpenAPI操作ID
オプション
オプションの操作クエリあるいはヘッダパラメータ
引数
必須の操作パスパラメータ
リクエスト本文
オプションのリクエスト本体.CLI Shorthand コマンドで.
それ以外は、発生する行為もある--help 出力:マークダウン説明と出力JSONスキーマを処理する必要があります.
このようにして、OpenAPI 3 YAMLにマップされます.

Github APIの例

現実世界の例を見てみましょうGithub V3 OpenAPI . コード検索操作の切り捨てられたバージョンです.

"/search/code":
  get:
    summary: Search code
    operationId: search/code
    parameters:
    - name: q
      description: The query contains one or more search keywords...
      in: query
      required: true
      schema:
        type: string
    - name: sort
      description: Sorts the results of your query...
      in: query
      required: false
      schema:
        type: string
        enum:
        - indexed
    - "$ref": "#/components/parameters/order"
    - "$ref": "#/components/parameters/per-page"
    - "$ref": "#/components/parameters/page"
    responses:
      '200':
        description: Response
        content:
          application/json:
            schema:
              type: object
              required:
              - total_count
              - incomplete_results
              - items
              properties:
                total_count:
                  type: integer
                incomplete_results:
                  type: boolean
                items:
                  type: array
                  items:
                    "$ref": "#/components/schemas/code-search-result-item"
            examples:
              default:
                "$ref": "#/components/examples/code-search-result-item-paginated"
      '304':
        "$ref": "#/components/responses/not_modified"
      '503':
        "$ref": "#/components/responses/service_unavailable"
      '422':
        "$ref": "#/components/responses/validation_failed"
      '403':
        "$ref": "#/components/responses/forbidden"

これは、次のコマンドのヘルプには、それを使用する方法を示すrestishに翻訳します.操作IDsearch-code とパラメータ--sort and --per-page から$ref 以上です.応答は、応答スキーマの端末に優しい表現を生成するために使用されます.

$ restish github search-code --help
Description truncated for example...

## Response 200 (application/json)

`schema
{
  incomplete_results: (boolean)
  items: [
    {
      git_url: (string)
      html_url: (string)
      name: (string)
      path: (string)
      repository: {
        archive_url: (string)
        assignees_url: (string)
        blobs_url: (string)
        branches_url: (string)
        collaborators_url: (string)
        comments_url: (string)
        commits_url: (string)
        compare_url: (string)
        contents_url: (string)
        contributors_url: (string)
        description: (string)
        downloads_url: (string)
        events_url: (string)
        fork: (boolean)
        forks_url: (string)
        full_name: (string)
        git_commits_url: (string)
        git_refs_url: (string)
        git_tags_url: (string)
        hooks_url: (string)
        html_url: (string)
        id: (number)
        issue_comment_url: (string)
        issue_events_url: (string)
        issues_url: (string)
        keys_url: (string)
        labels_url: (string)
        languages_url: (string)
        merges_url: (string)
        milestones_url: (string)
        name: (string)
        node_id: (string)
        notifications_url: (string)
        owner: {
          avatar_url: (string)
          events_url: (string)
          followers_url: (string)
          following_url: (string)
          gists_url: (string)
          gravatar_id: (string)
          html_url: (string)
          id: (number)
          login: (string)
          node_id: (string)
          organizations_url: (string)
          received_events_url: (string)
          repos_url: (string)
          site_admin: (boolean)
          starred_url: (string)
          subscriptions_url: (string)
          type: (string)
          url: (string)
        }
        private: (boolean)
        pulls_url: (string)
        stargazers_url: (string)
        statuses_url: (string)
        subscribers_url: (string)
        subscription_url: (string)
        tags_url: (string)
        teams_url: (string)
        trees_url: (string)
        url: (string)
      }
      score: (number)
      sha: (string)
      url: (string)
    }
  ]
  total_count: (number)
}
`

Usage:
  restish github search-code [flags]

Flags:
      --accept application/vnd.github.v3+json   Setting to...
  -h, --help                                    help for search-code
      --order desc                              Determines whether the first...
      --page int                                Page number of the results to fetch. (default 1)
      --per-page int                            Results per page (max 100) (default 30)
      --q string                                The query contains one or more search...
      --sort indexed                            Sorts the results of your query...

Global Flags:
...

すべてのパラメータがダブルスラッシュを使用することにも注意してください.-- ), 単一のスラッシュは、restish使用のために予約されているので.逆に、すべてのrestishパラメータは--rsh- 衝突を防ぐために.
要求された引数および/またはボディを持つ操作については、resCityは、使用例とドキュメントの例を生成することができます.たとえば、新しいREPOフォークを作成するとき:

## Request Schema (application/json)

`schema
{
  organization: (string) Optional parameter to specify the organization name if forking into an organization.
}
`

...

Usage:
  restish github repos-create-fork owner repo [flags]

Examples:
  restish repos-create-fork owner repo organization: string
  restish repos-create-fork owner repo <input.json

オーバーライド

場合によっては、CLI操作名やパラメーター名がAPIに正式な名前があるか、特定の推奨されていないパラメーターを非表示にするか、自動的にAuthを構成する方法を自動的に設定する必要があります.これらはすべて可能ですRestish OpenAPI Extensions .
名称
説明x-cli-aliases操作のコマンドエイリアスを設定します.x-cli-config自動CLI設定の設定.x-cli-descriptionCLIの代替説明を提供します.x-cli-ignoreこのパス、操作、またはパラメータを無視します.x-cli-hiddenこのパスまたは操作を非表示にします.x-cli-nameCLIの代替名を指定します.
たとえば、上記の検索操作では、クエリパラメータがq としてrestishで表示されます--q それはとても友好的ではない.を介して名前を変更することがありますx-cli-name: query 人々が使うことができるように--query 代わりに.

結論

うまくいけば、これはどのようにRextishが動的にOpenAPI仕様からCLIコマンドを生成することができるかについて若干の明かりを捨てました、そして、あなたがすでにバックエンドAPIに精通しているならば、あなたはそれらのコマンドが作動するのを予想することができます.