Rails API 用の Swagger Docs を生成する方法

RailsアプリケーションのAPIを作るのは、Ruby on Rails開発者にとっては簡単だ。いずれにせよ、顧客側のアプリケーションがなければ、APIが正常に動作しているかどうかをさまざまな顧客/顧客がどうやって知ることができるでしょうか。Railsアプリケーション内のAPIをレポートできるような答えはありますか？答えはイエスです。

この記事では、swagger UIを使ってRails APIドキュメントを作成する方法を公開します。

前提条件
ここでは、APIコールを提供する投稿アプリケーションのサンプルを使用する。

宝石
swagger UIをRails APIに統合するには、swagger-docsというgemを使います。このgemをアプリケーションのGemfileに追加し、bundle installします。

Swaggerイニシャライザーファイル:-)
gemをバンドルした後、config/initializers(swagger.rbなど)にイニシャライザを作成し、以下のオプションを指定します：

#ファイル config/initializers/swagger.rb
  Swagger::Docs::Config.register_apis({」を追加します。
  "1.0" => {
    #APIに使用する拡張子
    :api_extension_type => :json、
    # .jsonファイルが書き込まれる出力先
    :api_file_path => "public/apidocs"、
    #あなたのAPIへのURLベースパス
    :base_path => "http://localhost:3000"、
    1世代ごとにすべての.jsonファイルを削除する場合、#
    :clean_directory => trueとします、
    # api-docsにカスタム属性を追加します。
    :attributes => {
      :info => {
        "title" =>; "アプリケーションのタイトル"、
        "description" =>; "Swagger UIによるRails APIドキュメント"、
        "termsOfServiceUrl" => ""、
        "contact" => ""
       }
     }
  }
})

コンフィギュレーションの一覧は以下のURLを参照。
https://github.com/richhollis/swagger-docs#configuration-options

swagger_controllerとswagger_APIは、swagger UIドキュメントを提供するヘルパーです。

モジュールApi

モジュール V1

  class PostsController < ApplicationController

         response_to :json
         swagger_controller :posts, '投稿コントローラー'
         swagger_api :create do
               summary '投稿を作成する'
               notes '投稿の作成に使用する'
               param :form, '投稿[名前]', :string, :required, '名前'
               param :form, 'post[publish]', :boolean, :required, '公開'
          終了
          swagger_api :index do
                summary 'すべての投稿を取得する'
                notes 'すべての投稿を取得するために使用する'
                param :header, :Authoraization, :string, :required, '認証'.
                レスポンス :unauthorized
                response :ok, "成功"
          終了
          swagger_api :show do
                summary 'すべての投稿を取得する'
                notes '投稿を取得する際に使用する'
                param :path, :id, :string, :id
                レスポンス :unauthorized
                response :ok, "成功"
           終了
           swagger_api :destroy do
                 summary '投稿を破棄する'
                 notes '投稿を破棄する際に使用する'
                 param :path, :id, :string, :id
                 レスポンス :unauthorized
                 response :ok, "成功"
            終了
       終了
   終了
終了

元：-

param :header, :Authoraization, :string, :required, 'リクエストを認可する。
param :path, :id, :integer, :required, 'レコードを取得する投稿ID'
param :form, :name, :string, :optional, '投稿の名前'.
param :query, :query_name, :string, :optional, 'クエリ名' を指定します。

param - 標準 API パラメータ．

 最初の値: parameter_type(タイプ: form, path, header, query)
2番目の値: パラメータの名前
 3番目の値: パラメータのデータ型
 5番目の値: 必須/任意
 5番目の値パラメータに関する小さな説明
 6番目の値: 列挙型を表す括弧内の値のリスト(オプション)

列挙型を扱うには
列挙型の値のリストを渡す。
元：-

param_list :form, :payment_type, :string, :required, '支払いタイプ'、
[:小切手、:現金、:電信送金、:手形要求]]。

jsonファイルの生成

rake swagger:docs (このコマンドではデフォルトでエラーは表示されません)

すべてのエラーメッセージを見るには、以下のコマンドを使用する：

SD_LOG_LEVEL=1 rake swagger:docs

Swagger UIの統合

swagger uiをダウンロードしてください。
https://github.com/richhollis/swagger-docs-sample/tree/master/public/api

その前に、以下のコードを swagger.rb に追加してください。
APIとAPIドキュメントのパスを区別する。

クラス Swagger::Docs::Config
  def self.transform_path(path, api_version)
    # APIとAPIドキュメントのパスを区別する。
    "apidocs/#{パス}"
  エンド
終了

publicの下にapidocsディレクトリを、apidocsの下にapiディレクトリを作成する。

ダウンロードしたswagger-uiをpublic/apidocs/apiに、index.htmlをpublic/apidocsにコピーします。

index.htmlを編集する
window.swaggerUi関数のswaggerのurlをurlに変更："/apidocs/api-docs.json "に変更。
public/apidocsの下にあるapi-docs.jsonファイルを指すべきである。
なぜなら、swagger.rbで定義した設定に従って、そのパスの下に生成されるからです。

これで準備は完了だ。もしサーバーを動かしているのであれば、railsサーバーを停止して再起動してください。ブラウザで「http://localhost:3000/apidocs/indexâ」にアクセスしてみてください。各リソース（投稿など）で利用可能なリンク（表示/非表示、操作の一覧、操作の展開、Raw）をクリックすることができます：

こちらもお読みください: Paper Trail Gemでモデルデータの変更を追跡

こちらもお読みください：  PostgreSQL スキーマを使用したマルチテナント アーキテクチャ

私たちのRails開発スキルと過去のプロジェクトについてもっと知りたいですか？ 連絡する 今すぐ私たちと！