GraphSQL APIの静的ドキュメントの作成

APIドキュメントを書く主な理由は、APIを使用したい他の開発者に理解できるようにすることです.GraphSQL APIは、APIやドキュメントのサンドボックスとして機能するインタラクティブな遊び場だけを持っています.しかし、GraphQLでの作業は、過去の残りのAPIで動作する開発者に非常に混乱することができます.それはあなたのAPIにインタラクティブな例への参照を静的ドキュメントを追加するには、GraphSQLと非技術的な人々に新しい開発者のための完璧な意味になります.同様に、OpenAPIやSwaggerの仕様に基づいてREST APIのドキュメントを動的に作成することができますので、GraphSQL SDLに基づいてドキュメントを生成できます.このポストでは、SetZen APIテンプレートとSpectaqlと呼ばれるライブラリを使用してこれを行う方法を学びます.

TL;DR: You can find the repository with the complete source code for this post here.

GraphSQL APIの設定
ドキュメントを作成する前に、まずGraphSQL APIを作成する必要があります.Stezenを使用すると、すでに利用可能なAPIテンプレートを使用したり、カスタムのGraphSQLスキーマをデザインすることによって、数分以内にGraphSQL APIを作成できます.このポストでは、APIテンプレートを使用しますOpenWeatherMap API それはアドレスや座標に基づいて、世界中の200000都市以上の天気予報を提供することができます.
StepZenで新しいGraphSQL APIをセットアップするには、まずアカウントを作成し、取得したステップに従ってくださいhere . 次に新しいディレクトリを作成し、ローカルマシンのディレクトリに移動します.

mkdir my-api && cd my-api

このディレクトリでは、OpenWeatherMap APIのAPIテンプレートをインポートする次のコマンドを実行できます.

stepzen import openweathermap

CLIは、エンドポイント、推奨される名前、またはカスタムのいずれかの名前を指定するよう要求します.このポストでは、エンドポイントを指定できます.api/weatherreport .
OpenWeatherMap APIを使用するAPIキーを必要としないので、すぐにAPIを探索することから始めることができます.APIテンプレートのインポートが完了したら、コマンドを実行できます.

stepzen start

では、index.graphql and weatherreport/weatherreport.graphql あなたのローカルディレクトリで.このGraphical APIは、ローカルプロキシを通して利用できますweatherreport/weatherreport.graphql またはhttps://{stepzen_username}.stepzen.net/api/weatherreport/__graphql 置換する{stepzen_username} あなた自身で.
Graphqlを通して、GraphSQLスキーマで定義された1つの操作を見ることができますweatherReport クエリ.このクエリでは、緯度と経度の値である座標を指定する必要があります.これらの値を取得するには、緯度と経度の組み合わせに任意のアドレスを変換するジオコーディングを使用することができます簡単に地図上でそれを強調表示する.これらの値をブラウザから取得する方法はいくつかありますGeolocation API またはサードパーティ製のAPIを使用します.最初の1つは、Webアプリケーションを構築しているときに最も簡単ですので、今の2番目のオプションを使用してみましょう.ジオコーディングの最も人気のあるサードパーティのAPIの一つは、GoogleマップAPIです.このAPIを使用すると、住所、ワシントンD . C .のホワイトハウスに基づいて地理情報を要求することができますし、緯度経度の組み合わせを取得します.
あなたがAPIキーを要求している場合は、GoogleマップからAPIを使用することができますが、また、それらのマップからJavaScript APIdocumentation 直接.

住所で1600 Pennsylvania Avenue, Washington, D.C., USA , 座標を受け取る38.897663 and -77.036574 , 緯度経度組み合わせ.
これらの座標を使用すると、ホワイトハウスでは、次のクエリを使用して、Graphqlを使用して可能になったOpenWavelTheryを使用して、今日の天気をチェックできます.

query GetWeatherReport {
  weatherReport(latitude: 38.897663, longitude: -77.036574) {
    description
    feelsLike
    latitude
    longitude
    temp
    units
    date
  }
}

あなたが下のイメージで見ることができるように、このAPIの応答は我々のGraphiqlインタフェースの第2のパネルで返されます.

Graphqlのスキーマタブを使用して、応答の詳細情報を見つけることができます.これは、変数の意味を示します.あなたは、応答が天気(太陽の見込みで曇りのように)の説明、温度と温度単位を含むということを知っています.
しかし、あなたがGraphSQLに精通していないか、以前にあなた自身質問を作成しなかったならば、GraphSQL APIを内省するこの方法は非常に混乱することがありえます.したがって、Graphqlの遊び場でインタラクティブなドキュメントの横に静的ドキュメントを持つことは非常に役立つことができます.

静的ドキュメントの作成
The official documentation OpenWeatherMap REST APIの静的ドキュメントの優れた例です.これは、APIを使用して起動するテキストとコードの両方の例を提供します.休息APIのために、ドキュメンテーションはしばしば開いているAPIまたはswagger形式で定義されるそれらのAPI仕様から生成されます.GraphSQL APIはこの形式の仕様を持っていませんが、代わりにスキーマに依存します.前の節では、Graphqlプレイグラウンドを使用しました.これは、そのスキーマを使用して、GraphSQL APIからすべての情報を取得するためのイントロスペクションクエリを使用します.しかし、この内訳クエリは、このGraphSQLスキーマの静的ドキュメントも生成できます.
このために、私たちはSpectaQL , これはオープンAPIとswaggerの仕様で動作する人気のライブラリの光景に基づいています.SpectaqlはNPMからあなたのマシンにグローバルにインストールできます.

npm install -g spectaql

インストールが完了したら、config.yaml プロジェクトのルートに配置できるファイル

spectaql:
  logoFile: ./logo.svg

introspection:
  url: '{stepzen_api_endpoint}'
  headers:
    Authorization: 'apikey {stepzen_api_key}'

info:
  title: StepZen - OpenWeatherMap GraphQL API
  description:
    'Access current weather data for any location on Earth including over 200,000 cities. Using GraphQL!


    [View GraphiQL playground](http://localhost:5000/api/weatherreport)'
  contact:
    name: StepZen Support
    url: https://stepzen.com/docs
    email: [email protected]

servers:
  - url: '{stepzen_api_endpoint}'
    description: Production
    production: true

このファイルでは、GraphSQL APIが{stepzen_api_endpoint}, この関数を使用すると、OpenWeatherMap APIのGraphSQLインスタンスが実行されている場所にエンドポイントを置き換える必要があります.

This GraphQL API will be available through a local proxy at weatherreport/weatherreport.graphql or directly from https://{stepzen_username}.stepzen.net/api/weatherreport/__graphql (replace {stepzen_username} with your own).

また、あなたのStezen Zenキーを定義する必要があります{stepzen_api_key} ), あなたが見つけることができますaccount page , このURLはセキュリティ上の理由で認証でのみアクセス可能です.また、ドキュメントに追加されるロゴ、説明、および連絡先の詳細のような追加のメタデータを渡しました.

When you're running stepzen start on your local machine, it will also make an instance of GraphiQL available at http://localhost:5000/api/weatherreport; this endpoint is only available on your local device. It shouldn't be used to access this GraphQL API unless to use GraphiQL.

これでspectaqlを実行して、ドキュメントを作成することができます.これはマシンによっては1分ほどかかります.

npx spectaql -D config.yml

spectqlはドキュメントと呼ばれる新しいディレクトリを作成しますpublic JavaScript、HTML、およびCSSから成ります.で定義したロゴファイルへのローカルパスconfig.yml 意志は、この新しくつくられたディレクトリにロゴをコピーするのに用いられます.ファイルを開くことでドキュメントを見ることができますpublic/index.html ブラウザでは、次のようになります.

メタデータの他にconfig.yml, このAPI APIのスキーマは、すべての可能な操作と型を一覧表示し、それらをドキュメント化するために内省されます.戻り値の型の操作にはまだ追加情報はありませんが、GraphSQL SDLでこれらを直接追加できます.スキーマ内のこれらの説明はspectqlで解析され、静的ドキュメントに表示されます.ファイルにweatherreport/weatherreport.graphql , 次のように追加できます.

"""
A type that describes the weather report and its
fields
"""
type WeatherReport {
  date: Date!
  "City geo location, latitude"
  latitude: Float!
  "City geo location, longitude"
  longitude: Float!
  temp: Float
  feelsLike: Float
  description: String
  units: String
}

type Query {
  """
  Call current weather data for one location by
  geographic coordinates
  """
  weatherReport(
    "City geo location, latitude"
    latitude: Float!
    "City geo location, longitude"
    longitude: Float!
  ): WeatherReport
    @connector(
      type: "__openweathermap_weather_location_connector__"
      configuration: "owm_default"
    )
}

タイプの説明WeatherReport とweatherReport クエリは、複数行の説明として追加されますが、これらのタイプのフィールドと引数が1行で追加されます.これらの説明がスキーマに含まれている場合、それらはイントロスペクションのクエリを使用して使用できます.これは、InspecspectionクエリがSchemTqlからのGraphSQLプレイグラウンドと静的ドキュメントジェネレータの両方にスキーマ情報を追加するときに重要です.

または直接あなたがURLに達することができるGraphqlから説明を表示するhttp://localhost:5000/api/weatherreport .

結論と次のステップ
任意のGraphSQL APIのドキュメントは、任意のGraphSQL APIを探索するための簡単で強力な方法です.IntrospectionクエリはGraphSQLスキーマに関する情報を与え、GraphSQLやSpectaqlのような他のツールで使用されます.GraphSQLを使用すると、GraphSQLスキーマを内省し、GraphSQLのエンドポイントに対して使用可能な操作を実行できるプレイグラウンドへのアクセスを取得します.しかし、すべてのレベルのユーザーがあなたのGraphSQL APIと統合することを望むならば、Graphqlのような遊び場を持つことは十分でありません.したがって、あなたのエンドポイントに関する静的ドキュメンテーションを加えることは、良い追加でありえます.オープンソースライブラリSpectaqlを使えば、いくつかの行のコードですべてを行うことができます.また、GraphSQLのSDLを使用して、型、フィールド、引数、および操作の説明を追加できます.
次は何かこれまでのところ、ローカルでGraphSQL APIに基づいて静的ドキュメントを作成する方法を学びましたが、次のステップはこれをCI/CDに統合し、このドキュメントをサーバーに配備することです.あなたのCI/CDと組み合わせることは、あなたの配備手順にSpectaqlを走らせるためにコマンドを加えることによってされることができます.同時に、Stezzenはintegrated with Netlify 静的ドキュメントを展開します.このポストの完全なソースコードでリポジトリを見つけることができますhere .
もっと知りたいStepZen ? ここでそれを試したり、不和の上の任意の質問を求めるhere .