Skip to content
This repository has been archived by the owner on Dec 19, 2023. It is now read-only.

Commit

Permalink
Simplify includes in section snippet (#220)
Browse files Browse the repository at this point in the history 
* Simplify includes in section snippet

* Make clear that section snippets are not supported with Markdown
  • Loading branch information
@fbenz
fbenz authored Mar 29, 2018
1 parent 1e97f6c commit 499de90
Show file tree
Hide file tree
Showing 4 changed files with 61 additions and 56 deletions.
6 changes: 3 additions & 3 deletions ...resources/org/springframework/restdocs/templates/asciidoctor/default-auto-section.snippet
View file
Original file line number Diff line number Diff line change
@@ -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}}
12 changes: 0 additions & 12 deletions ...in/resources/org/springframework/restdocs/templates/markdown/default-auto-section.snippet
View file
Original file line number Diff line number Diff line change
@@ -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}}
97 changes: 56 additions & 41 deletions ...uto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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()
Expand All @@ -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()
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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()
Expand All @@ -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()
Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions spring-auto-restdocs-docs/section-snippet.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 499de90

Please sign in to comment.