ドキュメントを作成するには、いくつかの基本的なアプローチがあります。
- ドキュメントを手動で書くだけです。
- コード内のコメントのドキュメントを自動的に生成します。
- コードドキュメントの自動生成。
前者の場合、デメリットは明らかであり、マニュアルをマニュアルで管理する必要があります。さらに、マニュアルのテキストはコードから分離されています。 2番目のケースでは、ドキュメントはほとんどの場合、クラス、メソッド、および関数に関するコメントから生成されます。 この場合、最新の説明を維持する方がはるかに簡単です。さらに、関数署名がコメント内のパラメーターの説明と一致するなど、追加のチェックが行われる場合があります。 自動コード生成により、APIメソッドの最新の記述をサポートする問題が解消されます。 これらのメソッドは、ライブラリのドキュメント化に広く使用されています。 ただし、WEB APIの自動生成は非常にまれです。考えられる理由の1つは、そのようなジェネレーターがすべてフレームワークに依存しており、Webフレームワークとプログラミング言語からのリフレクションのサポートが必要なことです。
ここで、ドキュメントをコンパイル（および使用）するためのあまり一般的ではないいくつかの方法を簡単に検討します。
- 機械可読ドキュメントを作成し、そこからサーバーおよびクライアントコードテンプレートのコードを生成します。
- 機械可読なドキュメントがあるため、APIの動作とドキュメントの説明の対応をテストでチェックします。たとえば、メソッドの応答がドキュメントに書かれている内容に対応していることを確認します。
API実装自体を作成する前に、APIドキュメント（機械可読ドキュメントを含む）が必要になる理由をすぐに説明します。 ほとんどの場合、この状況は、APIサーバーとクライアントコードの両方が同時に開発されているときに発生します。 クライアント開発の段階で機械可読なドキュメントがあるため、APIクライアント自体と実際の回答をエミュレートするサーバーの両方を生成することが可能になります。
また、GRPC、Apache Thriftなどのプロトコルでは、実際にAPIの機械可読な記述を最初に記述（および維持）し、次に実装を記述しますが、プロトコル記述でファイルを絶えず編集する必要があるため、間違いなく厄介な効果をもたらすことができますが、一方、少なくとも署名の説明は現実に対応していることを常に確信しています。
そして、ドキュメントを取得する最後の（このテキストの）方法：
- サーバーからの実際の応答に対するAPIメソッドのドキュメントを生成します。 サーバーへのリクエストはテスト用にエンコードされます。
そして今、これがタイトルの主題です。 テストコードはテスト対象システムの不可欠な部分であるため、テストに追加の機能を非常に安価に配置できます。 この方法の利点を強調します。
- ドキュメント内には、APIメソッドからの回答の100％関連する例と、テストで個別にカバーされている場合に考えられるすべてのユースケースが含まれています。
- サービスのソースコードを変更せずにドキュメントを自動的に生成できます。 したがって、特定のフレームワークまたはテクノロジーを使用した自動ドキュメントのサポートに依存しなくなりました。
- 一般に、サービスのソースコードにアクセスできない場合がありますが、機械可読なドキュメントを含めて入手し、そのすべての利点を使用できます。
この例では、 Swagger仕様を使用してAPIを文書化します。このようなレビューは十分にあるため、このツールの一般的な説明は省略します。 しかし、これは、人間が理解できるドキュメントと、記述されたAPIを操作するためのサーバーおよびクライアントコードテンプレートの両方を生成できる機械可読ドキュメントであることに注意してください。
ネットワークの広大さで、 rspec-rails- swaggerとrswag gemが見つかりました。 残念ながら両方とも最低限のものがありますが、レールに拘束されます。 宝石には、例とかなり単純なコードを含む非常に詳細なドキュメントがあります。 実験として、私はRailsのrspec-rails-swagger gemを解き 、既存の機能テストに接続しました。
メソッドのドキュメントを生成するためのテストの説明は次のとおりです。
describe 'swagger_docs' do let(:movies_resp_body) { File.read('spec/fixtures/movies.json') } path '/movies' do operation "GET", summary: "respond 200 OK" do parameter :rating, in: :query, type: :string, required: false, description: "filter by rating" response 200, description: "successful" do schema( type: :array, items: { type: :string, } ) end end end end
このコードは実行テストを実行し、Rspec構文拡張を使用して、swaggerファイルの生成に使用されるメタ情報を指定します。
長いコマンドでrspecを実行します。
bundle exec rspec -f RSpec::Rails::Swagger::Formatter --order defined -t swagger_object
-tフラグフィルターは、特別なgem構文を使用するものによってのみテストを実行します。 -fフラグを使用すると、フォーマッターは結果をswagger jsonファイルとして出力できます。
コマンド出力は、swagger-uiにロードできる有効なswaggerファイルを生成するか、それを使用してAPIのクライアントを生成しようとします。
最終的に、Rspecフレームワークの機能テストを行い、スワガドキュメントを生成します。これにより、他のプログラミング言語のクライアントAPIをすばやく取得できます。 完全なリストの例 。
要約すると：
- 自動化されたドキュメントは、APIからの期待と厳しい変更可能な現実との最小限の一致を保証します。
- 場合によっては、開発者は最初にAPIメソッドを記述し、次に実装（GRPC、Apache Thriftプロトコル）を記述することを物理的に強制されます。
- 自動生成された機械可読ドキュメントは、開発段階とサポートの段階の両方で生活を簡素化し、APIを操作できます。
- 特別なツールを使用すると、ソースコードを変更することなく、機械で読み取り可能なドキュメントを生成できます。