From 499de90f0394e63911677efe60e4471c7f758df2 Mon Sep 17 00:00:00 2001 From: Florian Benz Date: Thu, 29 Mar 2018 11:25:14 +0200 Subject: [PATCH] Simplify includes in section snippet (#220) * Simplify includes in section snippet * Make clear that section snippets are not supported with Markdown --- .../asciidoctor/default-auto-section.snippet | 6 +- .../markdown/default-auto-section.snippet | 12 --- .../restdocs/section/SectionSnippetTest.java | 97 +++++++++++-------- .../section-snippet.adoc | 2 + 4 files changed, 61 insertions(+), 56 deletions(-) diff --git a/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-auto-section.snippet b/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-auto-section.snippet index 4f30effd..34dfbf2d 100644 --- a/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-auto-section.snippet +++ b/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-auto-section.snippet @@ -1,12 +1,12 @@ [[resources-{{link}}]] === {{title}} -include::{snippets}/{{path}}/auto-method-path.adoc[] +include::auto-method-path.adoc[] -include::{snippets}/{{path}}/auto-description.adoc[] +include::auto-description.adoc[] {{#sections}} ==== {{header}} -include::{snippets}/{{path}}/{{fileName}}.adoc[] +include::{{fileName}}.adoc[] {{/sections}} \ No newline at end of file diff --git a/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-auto-section.snippet b/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-auto-section.snippet index 4f30effd..e69de29b 100644 --- a/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-auto-section.snippet +++ b/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-auto-section.snippet @@ -1,12 +0,0 @@ -[[resources-{{link}}]] -=== {{title}} - -include::{snippets}/{{path}}/auto-method-path.adoc[] - -include::{snippets}/{{path}}/auto-description.adoc[] -{{#sections}} - -==== {{header}} - -include::{snippets}/{{path}}/{{fileName}}.adoc[] -{{/sections}} \ No newline at end of file diff --git a/spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java b/spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java index f4afbbff..30973079 100644 --- a/spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java +++ b/spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java @@ -7,9 +7,9 @@ * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -37,26 +37,41 @@ import java.util.ArrayList; import java.util.Arrays; +import java.util.Collections; +import java.util.List; import capital.scalable.restdocs.i18n.TranslationRule; import capital.scalable.restdocs.javadoc.JavadocReader; import org.junit.Before; import org.junit.Rule; import org.junit.Test; +import org.junit.runners.Parameterized; import org.springframework.restdocs.AbstractSnippetTests; import org.springframework.restdocs.http.HttpDocumentation; import org.springframework.restdocs.templates.TemplateFormat; +import org.springframework.restdocs.templates.TemplateFormats; +import org.springframework.restdocs.test.ExpectedSnippets; +import org.springframework.restdocs.test.OperationBuilder; import org.springframework.web.method.HandlerMethod; -public class SectionSnippetTest extends AbstractSnippetTests { +public class SectionSnippetTest { private JavadocReader javadocReader; @Rule public TranslationRule translationRule = new TranslationRule(); - public SectionSnippetTest(String name, TemplateFormat templateFormat) { - super(name, templateFormat); + @Rule + public ExpectedSnippets snippets; + + @Rule + public OperationBuilder operationBuilder; + + public SectionSnippetTest() { + // Only runs for AsciiDoctor, because Markdown is not supported. + TemplateFormat templateFormat = TemplateFormats.asciidoctor(); + this.snippets = new ExpectedSnippets(templateFormat); + this.operationBuilder = new OperationBuilder(templateFormat); } @Before @@ -72,8 +87,8 @@ public void noSnippets() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-noSnippets]]\n" + "=== Get Item By Id\n\n" + - "include::{snippets}/noSnippets/auto-method-path.adoc[]\n\n" + - "include::{snippets}/noSnippets/auto-description.adoc[]\n")); + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n")); new SectionBuilder() .snippetNames() @@ -91,8 +106,8 @@ public void noHandlerMethod() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-noHandlerMethod]]\n" + "=== No Handler Method\n\n" + - "include::{snippets}/noHandlerMethod/auto-method-path.adoc[]\n\n" + - "include::{snippets}/noHandlerMethod/auto-description.adoc[]\n")); + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n")); new SectionBuilder() .snippetNames() @@ -112,22 +127,22 @@ public void defaultSnippets() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-defaultSnippets]]\n" + "=== Get Item By Id\n\n" + - "include::{snippets}/defaultSnippets/auto-method-path.adoc[]\n\n" + - "include::{snippets}/defaultSnippets/auto-description.adoc[]\n\n" + + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n\n" + "==== Authorization\n\n" + - "include::{snippets}/defaultSnippets/auto-authorization.adoc[]\n\n" + + "include::auto-authorization.adoc[]\n\n" + "==== Path parameters\n\n" + - "include::{snippets}/defaultSnippets/auto-path-parameters.adoc[]\n\n" + + "include::auto-path-parameters.adoc[]\n\n" + "==== Query parameters\n\n" + - "include::{snippets}/defaultSnippets/auto-request-parameters.adoc[]\n\n" + + "include::auto-request-parameters.adoc[]\n\n" + "==== Request fields\n\n" + - "include::{snippets}/defaultSnippets/auto-request-fields.adoc[]\n\n" + + "include::auto-request-fields.adoc[]\n\n" + "==== Response fields\n\n" + - "include::{snippets}/defaultSnippets/auto-response-fields.adoc[]\n\n" + + "include::auto-response-fields.adoc[]\n\n" + "==== Example request\n\n" + - "include::{snippets}/defaultSnippets/curl-request.adoc[]\n\n" + + "include::curl-request.adoc[]\n\n" + "==== Example response\n\n" + - "include::{snippets}/defaultSnippets/http-response.adoc[]\n")); + "include::http-response.adoc[]\n")); new SectionBuilder().build() .document(operationBuilder @@ -149,14 +164,14 @@ public void customSnippets() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-customSnippets]]\n" + "=== Get Item By Id\n\n" + - "include::{snippets}/customSnippets/auto-method-path.adoc[]\n\n" + - "include::{snippets}/customSnippets/auto-description.adoc[]\n\n" + + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n\n" + "==== Example response\n\n" + - "include::{snippets}/customSnippets/http-response.adoc[]\n\n" + + "include::http-response.adoc[]\n\n" + "==== Response fields\n\n" + - "include::{snippets}/customSnippets/auto-response-fields.adoc[]\n\n" + + "include::auto-response-fields.adoc[]\n\n" + "==== Example request\n\n" + - "include::{snippets}/customSnippets/http-request.adoc[]\n")); + "include::http-request.adoc[]\n")); new SectionBuilder() .snippetNames(HTTP_RESPONSE, RESPONSE_FIELDS, HTTP_REQUEST) @@ -180,14 +195,14 @@ public void skipEmpty() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-skipEmpty]]\n" + "=== Get Item By Id\n\n" + - "include::{snippets}/skipEmpty/auto-method-path.adoc[]\n\n" + - "include::{snippets}/skipEmpty/auto-description.adoc[]\n\n" + + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n\n" + "==== Authorization\n\n" + - "include::{snippets}/skipEmpty/auto-authorization.adoc[]\n\n" + + "include::auto-authorization.adoc[]\n\n" + "==== Example request\n\n" + - "include::{snippets}/skipEmpty/curl-request.adoc[]\n\n" + + "include::curl-request.adoc[]\n\n" + "==== Example response\n\n" + - "include::{snippets}/skipEmpty/http-response.adoc[]\n")); + "include::http-response.adoc[]\n")); new SectionBuilder() .skipEmpty(true) @@ -211,8 +226,8 @@ public void customTitle() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-customTitle]]\n" + "=== Custom title\n\n" + - "include::{snippets}/customTitle/auto-method-path.adoc[]\n\n" + - "include::{snippets}/customTitle/auto-description.adoc[]\n")); + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n")); new SectionBuilder() .snippetNames() @@ -236,8 +251,8 @@ public void deprecated() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-deprecated]]\n" + "=== Get Item By Id (deprecated)\n\n" + - "include::{snippets}/deprecated/auto-method-path.adoc[]\n\n" + - "include::{snippets}/deprecated/auto-description.adoc[]\n")); + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n")); new SectionBuilder() .snippetNames() @@ -260,22 +275,22 @@ public void translation() throws Exception { this.snippets.expect(SECTION) .withContents(equalTo("[[resources-translation]]\n" + "=== Get Item By Id\n\n" + - "include::{snippets}/translation/auto-method-path.adoc[]\n\n" + - "include::{snippets}/translation/auto-description.adoc[]\n\n" + + "include::auto-method-path.adoc[]\n\n" + + "include::auto-description.adoc[]\n\n" + "==== XAuthorization\n\n" + - "include::{snippets}/translation/auto-authorization.adoc[]\n\n" + + "include::auto-authorization.adoc[]\n\n" + "==== XPath parameters\n\n" + - "include::{snippets}/translation/auto-path-parameters.adoc[]\n\n" + + "include::auto-path-parameters.adoc[]\n\n" + "==== XQuery parameters\n\n" + - "include::{snippets}/translation/auto-request-parameters.adoc[]\n\n" + + "include::auto-request-parameters.adoc[]\n\n" + "==== XRequest fields\n\n" + - "include::{snippets}/translation/auto-request-fields.adoc[]\n\n" + + "include::auto-request-fields.adoc[]\n\n" + "==== XResponse fields\n\n" + - "include::{snippets}/translation/auto-response-fields.adoc[]\n\n" + + "include::auto-response-fields.adoc[]\n\n" + "==== XExample request\n\n" + - "include::{snippets}/translation/curl-request.adoc[]\n\n" + + "include::curl-request.adoc[]\n\n" + "==== XExample response\n\n" + - "include::{snippets}/translation/http-response.adoc[]\n")); + "include::http-response.adoc[]\n")); new SectionBuilder().build() .document(operationBuilder diff --git a/spring-auto-restdocs-docs/section-snippet.adoc b/spring-auto-restdocs-docs/section-snippet.adoc index 4323d90a..4c0db56a 100644 --- a/spring-auto-restdocs-docs/section-snippet.adoc +++ b/spring-auto-restdocs-docs/section-snippet.adoc @@ -3,6 +3,8 @@ [[snippets-section]] === Section snippet +NOTE: Section snippets only work if AsciiDoc is used. Markdown is not supported, because Markdown has no includes. + The section snippet combines most common snippets into one convenient file. It helps you being even more lazy, because a single line of AsciiDoc is sufficient to document one endpoint. Assuming of course that you already documented your code with Javadoc.