SpringRestDocsを使用したREST APIの文書化とテスト

こんにちは、REST APIのドキュメント化のトピックに触れたいと思います。 この資料はすぐに予約を入れ、Springエコシステムで働くエンジニアに焦点を当てます。
いくつかの最近のプロジェクトでは、SpringRestDocsフレームワークを使用しましたが、ポートフォリオで正常に修正され、それを使い始めた知人にも見せられました。そして、その機能と利点についての記事で共有したいと思います。 この記事は、SpringRestDocsの使用方法を理解し、使用を開始するのに役立ちます。

このツールに慣れた瞬間から、私は待ち望んでいたソリューションがあり、開発では不十分であることに気付きました。 自分で判断してください-あなたはそれについてのみ夢を見ることができます：

• ドキュメントは、テストの実行時に自動的に生成されます。
• ドキュメントファイルのソース形式を制御できます。たとえば、htmlをコンパイルします。 Springブートを使用するため、gradleで手順とタスクを変更し、ドキュメントファイルをコピーしてjarに含め、リモートサーバーでドキュメントドキュメントを作成し、ドキュメントをアーカイブにコピーできます。 したがって、サービスがデプロイされている場所には常に、ドキュメントを備えた静的エンドポイントがあります。 オフラインバージョンの場合、pdf、epub、abookのアクセス許可を接続できます。
• RESTサービスのドキュメントは、作業ロジックに対応することが保証されています。 ドキュメントは、アプリケーションロジックと同期されます。 変更を加え、それらをドキュメントに反映するのを忘れていました-すぐに、非準拠の違いの詳細な説明とともに落下テストが表示されます。
• ドキュメントはテストから生成されます。 ここで、ドキュメントに新しいセクションを追加したり、ドキュメントの実行を開始したりするには、テストを作成することから始めます（はい、テスト）。 実際、非常に多くの場合、開発者は時間の不足、プロジェクトの未配信プロセス、またはその他の理由で大量のコードを記述しますが、テストの重要性に注意を払いません。 奇妙なことに、ドキュメントフレームワークはTDDでの作業を奨励しています
• その結果、カバレッジを高く保ちます。 より正確には、重要なのはコード分析システムやレポートに描かれるカバレッジの割合ではありません。 さまざまなシナリオを個別のテストでカバーし、その結果をドキュメントに含めることが重要です。 グリーンテストは常に楽しみです。

SpringRestDocsの作業を理解してみましょう。フレームワークを構成して使用できるものを読んだ後、この資料を理論上のインセットと組み合わせ、チュートリアルの実用的なラインをガイドします。

SpringRestDocsパイプライン

SpringRestDocsでの作業を開始するには、そのパイプラインの原理を理解する必要があります。これは非常にシンプルで線形です。



リソース検証のロジックを除き、すべてのアクションはテストから取得され、スニペットも生成されます。 スニペットは、コントローラーが対話した特定のHTTP属性のシリアル化された値です。 生成されたスニペットを含めるセクションを示す特別なテンプレートファイルを準備しています。 出力はコンパイルされたドキュメントファイルです。ドキュメント形式を設定できることに注意してください。形式はhtml、pdf、epub、abookです。

さらに記事のテキストに沿って、このパイプラインを収集し、テストを作成し、SpringRestDocsを構成し、ドキュメントをコンパイルします。

依存関係

以下は、スプリングレストドキュメントを操作するプロジェクトの依存関係です。この例では、作業を分析します。

dependencies { compile "org.springframework.boot:spring-boot-starter-data-jpa" compile "org.springframework.boot:spring-boot-starter-hateoas" compile "org.springframework.boot:spring-boot-starter-web" compile "org.springframework.restdocs:spring-restdocs-core:$restdocsVersion" compile "com.h2database:h2:$h2Version" compile "org.projectlombok:lombok" testCompile "org.springframework.boot:spring-boot-starter-test" asciidoctor "org.springframework.restdocs:spring-restdocs-asciidoctor:$restdocsVersion" testCompile "org.springframework.restdocs:spring-restdocs-mockmvc:$restdocsVersion" testCompile "com.jayway.jsonpath:json-path" } 

テスト可能なコントローラー

テストを記述し、SpringRestDocsを接続し、ドキュメントを生成するコントローラーの一部を示します。

 @RestController @RequestMapping("/speakers") public class SpeakerController { @Autowired private SpeakerRepository speakerRepository; @GetMapping(path = "/{id}") public ResponseEntity<SpeakerResource> getSpeaker(@PathVariable long id) { return speakerRepository.findOne(id) .map(speaker -> ResponseEntity.ok(new SpeakerResource(speaker))) .orElse(new ResponseEntity(HttpStatus.NOT_FOUND)); } 

そのロジックを見てみましょう。 SpringDataRepositoryの助けを借りて、コントローラーに渡されたIDを持つレコードのデータベースにアクセスします。 SpringDataRepositoryはOptionalを返します-値がある場合、JPAエンティティをリソースに変換します（同時に、応答に表示したくないフィールドの一部をカプセル化できます）。Optional.isEmpty（）の場合、404 NOT_FOUNDコードを返します。

SpeakerResourceリソースコード

 @NoArgsConstructor @AllArgsConstructor @Getter @Relation(value = "speaker", collectionRelation = "speakers") public class SpeakerResource extends ResourceSupport { private String name; private String company; public SpeakerResource(Speaker speaker) { this.name = speaker.getName(); this.company = speaker.getCompany(); add(linkTo(methodOn(SpeakerController.class).getSpeaker(speaker.getId())).withSelfRel()); add(linkTo(methodOn(SpeakerController.class).getSpeakerTopics(speaker.getId())).withRel("topics")); } } 

このエンドポイントの基本的なテストを書きましょう。

 @RunWith(SpringRunner.class) @SpringBootTest @AutoConfigureMockMvc @AutoConfigureRestDocs(outputDir = "build/generated-snippets") public class SpControllerTest { @Autowired private MockMvc mockMvc; @Autowired private SpeakerRepository speakerRepository; @After public void tearDown() { speakerRepository.deleteAll(); } @Test public void testGetSpeaker() throws Exception { // Given Speaker speaker = Speaker.builder().name("Roman").company("Lohika").build(); speakerRepository.save(speaker); // When ResultActions resultActions = mockMvc.perform(get("/speakers/{id}", speaker.getId())) .andDo(print()); // Then resultActions.andExpect(status().isOk()) .andExpect(jsonPath("name", is("Roman"))) .andExpect(jsonPath("company", is("Lohika"))); } } 

テストでは、自動構成mockMVC、RestDocsを接続します。 restdocsの場合、スニペットが生成されるディレクトリ（outputDir = "buid / generated-snippets"）を指定する必要があります。これは、mockMvcを使用した通常のテストです。 spring.tests mockMvc Dependenceの独自のライブラリを使用しますが、RestAssuredを使用する場合は、読むものもすべて関連します。わずかな変更のみがあります。 私のテストでは、コントローラーのHTTPメソッドを呼び出して、ステータス、フィールドを確認し、要求/応答フローをコンソールに出力します。

ResultsHandler

出力でテストを実行すると、次のように表示されます。

 MockHttpServletRequest: HTTP Method = GET Request URI = /speakers/1 Parameters = {} Headers = {} Handler: Type = smartjava.domain.speaker.SpeakerController Method = public org.springframework.http.ResponseEntity<smartjava.domain.speaker.SpeakerResource> smartjava.domain.speaker.SpeakerController.getSpeaker(long) Async: Async started = false Async result = null Resolved Exception: Type = null ModelAndView: View name = null View = null Model = null FlashMap: Attributes = null MockHttpServletResponse: Status = 200 Error message = null Headers = {Content-Type=[application/hal+json;charset=UTF-8]} Content type = application/hal+json;charset=UTF-8 Body = { "name" : "Roman", "company" : "Lohika", "_links" : { "self" : { "href" : "http://localhost:8080/speakers/1" }, "topics" : { "href" : "http://localhost:8080/speakers/1/topics" } } } 

これは、HTTP要求および応答コンテンツのコンソールへの出力です。 したがって、コントローラーに送信された値と、コントローラーからの応答を追跡できます。 コンソールへの出力は、接続されたハンドラーによって実行されます。

  resultActions.andDo(print()); 

ResultHandlerは機能的なインターフェースです。 独自の実装を作成してテストで接続すると、テストで実行されたHttpRequest / HttpResponseにアクセスし、実行結果を解釈できます（コンソール、ファイルシステム、独自のドキュメントファイルなどにこれらの値を記録する場合）。

 public interface ResultHandler { /** * Perform an action on the given result. * * @param result the result of the executed request * @throws Exception if a failure occurs */ void handle(MvcResult result) throws Exception; } 

Mvcresult

ご覧のとおり、ResultHandlerはMvcResultの値にアクセスして解釈することができます。これは、mockMvcテストの結果を含むオブジェクトであり、MockHttpServletRequest、MockHttpServletResponseの2つのキープレーヤーの属性にアクセスできます。 これらの属性のリストの一部を次に示します。



次に、呼び出されたHTTPメソッドのタイプと応答コードのステータスを記録するMyResultHandlerの例を示します。

 public class MyResultHandler implements ResultHandler { private Logger logger = LoggerFactory.getLogger(MyResultHandler.class); static public ResultHandler myHandler() { return new MyResultHandler(); } @Override public void handle(MvcResult result) throws Exception { MockHttpServletRequest request = result.getRequest(); MockHttpServletResponse response = result.getResponse(); logger.error("HTTP method: {}, status code: {}", request.getMethod(), response.getStatus()); } } 

  resultActions.andDo(new MyResultHandler()) 

Pivotalがドキュメントの生成に使用したのは、処理と登録に関するこの考え方です。 テストでは、MockMvcRestDocumentationクラスのハンドラーを接続する必要があります。

 // Document resultActions.andDo(MockMvcRestDocumentation.document("{class-name}/{method-name}")); 

スニペットを生成しましょう

テストを再度実行し、実行後、ファイルを含むフォルダーがbuild / generated-snippetsディレクトリーに作成されたことに注意してください。

 ./sp-controller-test/test-get-speaker: total 48 -rw-r--r-- 1 rtsypuk staff 68B Oct 31 14:17 curl-request.adoc -rw-r--r-- 1 rtsypuk staff 87B Oct 31 14:17 http-request.adoc -rw-r--r-- 1 rtsypuk staff 345B Oct 31 14:17 http-response.adoc -rw-r--r-- 1 rtsypuk staff 69B Oct 31 14:17 httpie-request.adoc -rw-r--r-- 1 rtsypuk staff 36B Oct 31 14:17 request-body.adoc -rw-r--r-- 1 rtsypuk staff 254B Oct 31 14:17 response-body.adoc 

これらは生成されたスニペットです。 デフォルトでは、rest docsは6種類のスニペットを生成しますが、そのうちのいくつかを示します。

スニペットは、テキスト形式のファイルにシリアル化されたHTTP要求/応答コンポーネントの一部です。 最も一般的に使用されるスニペットは、curl-request、http-request、http-response、request-body、response-body、リンク（HATEOASサービスの場合）、パスパラメーター、応答フィールド、ヘッダーです。

curl-request.adoc

 [source,bash] ---- $ curl 'http://localhost:8080/speakers/1' -i ---- 

http-request.adoc

 [source,bash] [source,http,options="nowrap"] ---- GET /speakers/1 HTTP/1.1 Host: localhost:8080 ---- 

http-response.adoc

 [source,bash] [source,http,options="nowrap"] ---- HTTP/1.1 200 OK Content-Type: application/hal+json;charset=UTF-8 Content-Length: 218 { "name" : "Roman", "company" : "Lohika", "_links" : { "self" : { "href" : "http://localhost:8080/speakers/1" }, "topics" : { "href" : "http://localhost:8080/speakers/1/topics" } } } ---- 

テンプレートファイルの準備

次に、テンプレートファイルを準備し、生成されたスニペットブロックが含まれるセクションをマークする必要があります。 テンプレートは柔軟なasciidoc形式で維持されます。デフォルトでは、テンプレートはsrc / docs / asciidocディレクトリにあります。

 == Rest convention include::etc/rest_conv.adoc[] == Endpoints === Speaker ==== Get speaker by ID ===== Curl example include::{snippets}/sp-controller-test/test-get-speaker/curl-request.adoc[] ===== HTTP Request include::{snippets}/sp-controller-test/test-get-speaker/http-request.adoc[] ===== HTTP Response ====== Success HTTP responses include::{snippets}/sp-controller-test/test-get-speaker/http-response.adoc[] ====== Response fields include::{snippets}/sp-controller-test/test-get-speaker/response-fields.adoc[] ====== HATEOAS links include::{snippets}/sp-controller-test/test-get-speaker/links.adoc[] 

asciidoc構文を使用して、静的ファイル（たとえば、rest_conv.adocファイルで、サービスがサポートするメソッドの説明を作成しました。この場合、どのステータスコードを返す必要があります）、および自動生成されたスニペットファイルを添付できます。

静的rest_conv.adoc

 === HTTP verbs Speakers Service tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs. |=== | Verb | Usage | `GET` | Used to retrieve a resource | `POST` | Used to create a new resource | `PATCH` | Used to update an existing resource, including partial updates | `PUT` | Used to update an existing resource, full updates only | `DELETE` | Used to delete an existing resource |=== === HTTP status codes Speakers Service tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes. |=== | Status code | Usage | `200 OK` | Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action. | `201 Created` | The request has been fulfilled and resulted in a new resource being created. | `204 No Content` | The server successfully processed the request, but is not returning any content. | `400 Bad Request` | The server cannot or will not process the request due to something that is perceived to be a client error (eg, malformed request syntax, invalid request message framing, or deceptive request routing). | `404 Not Found` | The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible. | `409 Conflict` | The request could not be completed due to a conflict with the current state of the target resource. | `422 Unprocessable Entity` | Validation error has happened due to processing the posted entity. |=== 

build.gradleを構成する

ドキュメントをコンパイルするには、基本的なセットアップを行う必要があります-必要な依存関係を接続し、asciidoctor-gradle-pluginをgradle.build buildscript.dependenciesに追加する必要があります

 buildscript { repositories { jcenter() mavenCentral() mavenLocal() maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "org.asciidoctor:asciidoctor-gradle-plugin:$asciiDoctorPluginVersion" classpath "org.springframework.boot:spring-boot-gradle-plugin:$springBootVersion" } } 

プラグインを適用する

 apply plugin: 'org.asciidoctor.convert' 

次に、基本的なasciidoctor構成を作成する必要があります。

 asciidoctor { dependsOn test backends = ['html5'] options doctype: 'book' attributes = [ 'source-highlighter': 'highlightjs', 'imagesdir' : './images', 'toc' : 'left', 'toclevels' : 3, 'numbered' : '', 'icons' : 'font', 'setanchors' : '', 'idprefix' : '', 'idseparator' : '-', 'docinfo1' : '', 'safe-mode-unsafe' : '', 'allow-uri-read' : '', 'snippets' : snippetsDir, linkattrs : true, encoding : 'utf-8' ] inputs.dir snippetsDir outputDir "build/asciidoc" sourceDir 'src/docs/asciidoc' sources { include 'index.adoc' } } 

ドキュメントアセンブリを確認して、コンソールで実行しましょう

 gradle asciidoctor 

asciidoctorタスクはテストの実行に依存することを示したため、最初にテストがブレークスルーし、スニペットを生成し、これらのスニペットが生成されたドキュメントに含まれます。

ドキュメント

説明したすべての構成手順は、プロジェクトを上げるときに一度実行する必要があります。 これで、テストを実行するたびに、スニペットとドキュメントが追加で生成されます。 私はいくつかのスクリーンショットをもたらします：

HTTPメソッドとステータスコードに関する契約セクション



すべてのスピーカーメソッドドキュメントの例の取得



同一のドキュメントもPDF形式で入手できます。 オフラインバージョンとして便利で、サービスの仕様とともに顧客に送信できます。

jarタスクの変更

さて、スプリングブートで作業しているので、興味深いプロパティの1つを使用できます-src / staticディレクトリまたはsrc / publicにあるすべてのリソースは、ブラウザーからアクセスすると静的コンテンツとして利用可能になります

 jar { dependsOn asciidoctor from ("${asciidoctor.outputDir}/html5") { include '**/index.html' include '**/images/*' into 'static/docs' } } 

これがまさに私たちが行うことです-ドキュメントを組み立てた後、それを/ static / docsディレクトリにコピーします。 したがって、収集された各jarアーティファクトには、ドキュメント付きの静的エンドポイントが含まれます。 それがどこにデプロイされるか、どの環境に置かれるかに関係なく、ドキュメントの現在のバージョンはいつでも入手可能です。

おわりに

これは、このすばらしいツールの機能のごく一部にすぎません。1つの記事ですべてを網羅することは不可能です。 SpringRestDocsに興味がある人のために、私はリソースへのリンクを提供しています：

• コンパイルされたドキュメントは次のようになります。この例ではasciidoc形式、このツールのパワフルさを確認できます（ちなみに、githubpagesにドックを自動的にダウンロードできます） tsypuk.imtqy.com/springrestdoc
• SpringRestDocs github.com/tsypuk/springrestdocでカスタマイズされたデモプロジェクトを使用したgithub （すべてを構成し、プロジェクトのコードを使用してクイックスタートします。デモ構文asciidoctor、拡張機能の例、図を簡単に生成してドキュメントに含めることができます）
• そしてもちろん公式文書