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

Commit ce165d1

Browse files
jmisurjmisur
authored
customization of existing snippets (#130)
* customization of existing snippets * fixed example * test fix * renamed all snippets * merge fix * fixed example docs * revert html reformat
1 parent b063569 commit ce165d1

36 files changed

+279
-271
lines changed

‎docs/index.html‎

Lines changed: 49 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -448,6 +448,7 @@ <h1>Spring Auto REST Docs</h1>
448448
<li><a href="#snippets-response-fields">Response fields snippet</a></li>
449449
<li><a href="#snippets-section">Section snippet</a></li>
450450
<li><a href="#snippets-custom">Custom snippet</a></li>
451+
<li><a href="#snippets-customization">Snippet customization</a></li>
451452
</ul>
452453
</li>
453454
<li><a href="#constraints">Documenting constraints</a>
@@ -1054,7 +1055,7 @@ <h3 id="snippets-section"><a class="link" href="#snippets-section">Section snipp
10541055
<div class="listingblock">
10551056
<div class="title">Asciidoc</div>
10561057
<div class="content">
1057-
<pre class="highlightjs highlight"><code class="language-asciidoc" data-lang="asciidoc">include::{snippets}/your-endpoint/section.adoc[]</code></pre>
1058+
<pre class="highlightjs highlight"><code class="language-asciidoc" data-lang="asciidoc">include::{snippets}/your-endpoint/auto-section.adoc[]</code></pre>
10581059
</div>
10591060
</div>
10601061
<div class="listingblock">
@@ -1063,9 +1064,9 @@ <h3 id="snippets-section"><a class="link" href="#snippets-section">Section snipp
10631064
<pre class="highlightjs highlight"><code class="language-asciidoc" data-lang="asciidoc">[[resources-{{link}}]]
10641065
=== {{title}}
10651066

1066-
include::{snippets}/{{path}}/method-path.adoc[]
1067+
include::{snippets}/{{path}}/auto-method-path.adoc[]
10671068

1068-
include::{snippets}/{{path}}/description.adoc[]
1069+
include::{snippets}/{{path}}/auto-description.adoc[]
10691070
{{#sections}}
10701071

10711072
==== {{header}}
@@ -1097,7 +1098,7 @@ <h3 id="snippets-section"><a class="link" href="#snippets-section">Section snipp
10971098
<tr>
10981099
<td class="tableblock halign-left valign-top"><p class="tableblock">{title}</p></td>
10991100
<td class="tableblock halign-left valign-top"><p class="tableblock">Get Item By Id</p></td>
1100-
<td class="tableblock halign-left valign-top"><p class="tableblock">See <a href="#snippets-customization-title">Section title</a>.</p></td>
1101+
<td class="tableblock halign-left valign-top"><p class="tableblock">See <a href="#snippets-section-customization-title">Section title</a>.</p></td>
11011102
</tr>
11021103
<tr>
11031104
<td class="tableblock halign-left valign-top"><p class="tableblock">{snippets}</p></td>
@@ -1188,9 +1189,9 @@ <h4 id="snippets-section-configuration"><a class="link" href="#snippets-section-
11881189
</table>
11891190
</div>
11901191
<div class="sect3">
1191-
<h4 id="snippets-customization"><a class="link" href="#snippets-customization">Customisation options</a></h4>
1192-
<div class="sect4">
1193-
<h5 id="snippets-customization-order"><a class="link" href="#snippets-customization-order">Sections and order</a></h5>
1192+
<h4 id="snippets-section-customization"><a class="link" href="#snippets-section-customization">Customisation options</a></h4>
1193+
<div class="sect4">
1194+
<h5 id="snippets-section-customization-order"><a class="link" href="#snippets-section-customization-order">Sections and order</a></h5>
11941195
<div class="paragraph">
11951196
<p>If you want to configure custom sections and their order, instead of using <code>AutoDocumentation.section()</code> you can use
11961197
<code>AutoDocumentation.sectionBuilder()</code> in the following manner:</p>
@@ -1221,19 +1222,19 @@ <h5 id="snippets-customization-order"><a class="link" href="#snippets-customizat
12211222
</table>
12221223
</div>
12231224
</div>
1224-
<div class="sect4">
1225-
<h5 id="snippets-customization-title"><a class="link" href="#snippets-customization-title">Section title</a></h5>
1226-
<div class="paragraph">
1227-
<p>Section title uses text from <code>@title</code> Javadoc tag on the handler method.
1228-
If missing, it&#8217;s derived from the method name, e.g. <code>getItemById</code> &#8594; <em>Get Item By Id</em>.</p>
1229-
</div>
1230-
<div class="paragraph">
1231-
<p>If you use <code>@title</code> tag and want to generate regular Javadoc we well,
1232-
you need to include this tag among custom tags in plugin configuration.</p>
1233-
</div>
1234-
<div class="listingblock">
1235-
<div class="title">Custom maven-javadoc-plugin configuration</div>
1236-
<div class="content">
1225+
<div class="sect4">
1226+
<h5 id="snippets-section-customization-title"><a class="link" href="#snippets-section-customization-title">Section title</a></h5>
1227+
<div class="paragraph">
1228+
<p>Section title uses text from <code>@title</code> Javadoc tag on the handler method.
1229+
If missing, it&#8217;s derived from the method name, e.g. <code>getItemById</code> &#8594; <em>Get Item By Id</em>.</p>
1230+
</div>
1231+
<div class="paragraph">
1232+
<p>If you use <code>@title</code> tag and want to generate regular Javadoc we well,
1233+
you need to include this tag among custom tags in plugin configuration.</p>
1234+
</div>
1235+
<div class="listingblock">
1236+
<div class="title">Custom maven-javadoc-plugin configuration</div>
1237+
<div class="content">
12371238
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml">&lt;plugin&gt;
12381239
&lt;artifactId&gt;maven-javadoc-plugin&lt;/artifactId&gt;
12391240
&lt;executions&gt;
@@ -1253,20 +1254,39 @@ <h5 id="snippets-customization-title"><a class="link" href="#snippets-customizat
12531254
&lt;/execution&gt;
12541255
&lt;/executions&gt;
12551256
&lt;/plugin&gt;</code></pre>
1256-
</div>
1257-
</div>
1258-
</div>
1257+
</div>
1258+
</div>
1259+
</div>
1260+
</div>
1261+
<div class="sect3">
1262+
<h4 id="snippets-section-custom-snippet"><a class="link" href="#snippets-section-custom-snippet">Custom snippet in section</a></h4>
1263+
<div class="paragraph">
1264+
<p>If you want your custom snippet to be part of section snippet with automatically recognised header and include link (file name),
1265+
you have to implement <a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSupport.java">SectionSupport</a> interface.
1266+
Then, inside MockMvc configuration, add this snippet to the list of snippets using documentation configuration&#8217;s
1267+
builder <code>withDefaults(&#8230;&#8203;)</code> and include snippet name among SectionBuilder&#8217;s <code>snippetNames(&#8230;&#8203;)</code>.</p>
1268+
</div>
12591269
</div>
12601270
</div>
12611271
<div class="sect2">
12621272
<h3 id="snippets-custom"><a class="link" href="#snippets-custom">Custom snippet</a></h3>
12631273
<div class="paragraph">
12641274
<p>Custom snippets are created by subclassing the <a href="https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/Snippet.java">Snippet</a> interface
1265-
(or more conveniently <a href="https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/TemplatedSnippet.java">TemplatedSnippet</a>). If you want your custom
1266-
snippet to be part of section snippet with automatically recognised header and include link (file name),
1267-
you have to implement <a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSupport.java">SectionSupport</a> interface.
1268-
Then, inside MockMvc configuration, add this snippet to the list of snippets using documentation configuration&#8217;s
1269-
builder <code>withDefaults(&#8230;&#8203;)</code> and include snippet name among SectionBuilder&#8217;s <code>snippetNames(&#8230;&#8203;)</code>.</p>
1275+
(or more conveniently <a href="https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/TemplatedSnippet.java">TemplatedSnippet</a>).
1276+
Template for the snippet must be put into <code>org/springframework/restdocs/templates/asciidoctor</code>
1277+
(optionally also <code>org/springframework/restdocs/templates/markdown</code>) resource package. The template name
1278+
must correspond with the snippet name passed to the class constructor.
1279+
You can also <a href="#snippets-section-custom-snippet">include your custom snippet in a section</a>.</p>
1280+
</div>
1281+
</div>
1282+
<div class="sect2">
1283+
<h3 id="snippets-customization"><a class="link" href="#snippets-customization">Snippet customization</a></h3>
1284+
<div class="paragraph">
1285+
<p>Provide your own template in <code>org/springframework/restdocs/templates/asciidoctor</code> (or <code>markdown</code>) package of your resources.
1286+
You can override <a href="https://github.com/spring-projects/spring-restdocs/tree/v1.2.1.RELEASE/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates">REST Docs templates</a>
1287+
and <a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates">Auto REST Docs templates</a>.
1288+
Important is to omit <code>default-</code> part from the template name so that the resolution algorithm will prefer this custom template.
1289+
See also <a href="http://docs.spring.io/spring-restdocs/docs/1.2.1.RELEASE/reference/html5/#documenting-your-api-customizing-snippets">original documentation</a> for additional details.</p>
12701290
</div>
12711291
</div>
12721292
</div>
@@ -1524,7 +1544,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
15241544
</div>
15251545
<div id="footer">
15261546
<div id="footer-text">
1527-
Last updated 2017-08-30 12:55:11 CEST
1547+
Last updated 2017-08-30 17:51:23 CEST
15281548
</div>
15291549
</div>
15301550
<link rel="stylesheet" href="highlight/styles/github.min.css">

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/SnippetRegistry.java‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@
77
import org.springframework.restdocs.operation.Operation;
88

99
public class SnippetRegistry {
10-
public static final String AUTHORIZATION = "authorization";
11-
public static final String DESCRIPTION = "description";
12-
public static final String METHOD_PATH = "method-path";
13-
public static final String PATH_PARAMETERS = "path-parameters";
14-
public static final String REQUEST_PARAMETERS = "request-parameters";
15-
public static final String REQUEST_FIELDS = "request-fields";
16-
public static final String RESPONSE_FIELDS = "response-fields";
10+
public static final String AUTHORIZATION = "auto-authorization";
11+
public static final String DESCRIPTION = "auto-description";
12+
public static final String METHOD_PATH = "auto-method-path";
13+
public static final String PATH_PARAMETERS = "auto-path-parameters";
14+
public static final String REQUEST_PARAMETERS = "auto-request-parameters";
15+
public static final String REQUEST_FIELDS = "auto-request-fields";
16+
public static final String RESPONSE_FIELDS = "auto-response-fields";
1717
public static final String CURL_REQUEST = "curl-request";
1818
public static final String HTTP_REQUEST = "http-request";
1919
public static final String HTTP_RESPONSE = "http-response";

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/AuthorizationSnippet.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929

3030
public class AuthorizationSnippet extends TemplatedSnippet implements SectionSupport {
3131

32-
public static final String AUTHORIZATION = "authorization";
32+
public static final String AUTHORIZATION = "auto-authorization";
3333

3434
private final String defaultAuthorization;
3535

@@ -41,7 +41,7 @@ public AuthorizationSnippet(String defaultAuthorization) {
4141
@Override
4242
protected Map<String, Object> createModel(Operation operation) {
4343
Map<String, Object> model = new HashMap<>();
44-
model.put(AUTHORIZATION, authorizationDescription(operation));
44+
model.put("authorization", authorizationDescription(operation));
4545
return model;
4646
}
4747

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/DescriptionSnippet.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131

3232
public class DescriptionSnippet extends TemplatedSnippet {
3333

34-
public static final String DESCRIPTION = "description";
34+
public static final String DESCRIPTION = "auto-description";
3535

3636
public DescriptionSnippet() {
3737
super(DESCRIPTION, null);
@@ -48,7 +48,7 @@ protected Map<String, Object> createModel(Operation operation) {
4848
methodComment = convertFromJavadoc(methodComment, determineForcedLineBreak(operation));
4949

5050
Map<String, Object> model = new HashMap<>();
51-
model.put(DESCRIPTION, methodComment);
51+
model.put("description", methodComment);
5252
return model;
5353
}
5454
}

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/MethodAndPathSnippet.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818

1919
import static capital.scalable.restdocs.OperationAttributeHelper.getRequestMethod;
2020
import static capital.scalable.restdocs.OperationAttributeHelper.getRequestPattern;
21-
import static capital.scalable.restdocs.SnippetRegistry.METHOD_PATH;
2221

2322
import java.util.HashMap;
2423
import java.util.Map;
@@ -28,7 +27,7 @@
2827

2928
public class MethodAndPathSnippet extends TemplatedSnippet {
3029

31-
public static final String METHOD_PATH = "method-path";
30+
public static final String METHOD_PATH = "auto-method-path";
3231

3332
public MethodAndPathSnippet() {
3433
super(METHOD_PATH, null);

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/payload/JacksonRequestFieldSnippet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
public class JacksonRequestFieldSnippet extends AbstractJacksonFieldSnippet {
2828

29-
public static final String REQUEST_FIELDS = "request-fields";
29+
public static final String REQUEST_FIELDS = "auto-request-fields";
3030

3131
private final Type requestBodyType;
3232
private final boolean failOnUndocumentedFields;

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/payload/JacksonResponseFieldSnippet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
public class JacksonResponseFieldSnippet extends AbstractJacksonFieldSnippet {
2828

29-
public static final String RESPONSE_FIELDS = "response-fields";
29+
public static final String RESPONSE_FIELDS = "auto-response-fields";
3030
public static final String SPRING_DATA_PAGE_CLASS = "org.springframework.data.domain.Page";
3131

3232
private final Type responseBodyType;

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/PathParametersSnippet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
public class PathParametersSnippet extends AbstractParameterSnippet<PathVariable> {
2323

24-
public static final String PATH_PARAMETERS = "path-parameters";
24+
public static final String PATH_PARAMETERS = "auto-path-parameters";
2525
private final boolean failOnUndocumentedParams;
2626

2727
public PathParametersSnippet() {

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/RequestParametersSnippet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525

2626
public class RequestParametersSnippet extends AbstractParameterSnippet<RequestParam> {
2727

28-
public static final String REQUEST_PARAMETERS = "request-parameters";
28+
public static final String REQUEST_PARAMETERS = "auto-request-parameters";
2929
public static final String SPRING_DATA_PAGEABLE_CLASS =
3030
"org.springframework.data.domain.Pageable";
3131

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSnippet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242

4343
public class SectionSnippet extends TemplatedSnippet {
4444

45-
public static final String SECTION = "section";
45+
public static final String SECTION = "auto-section";
4646

4747
private final RestDocumentationContextPlaceholderResolverFactory placeholderResolverFactory =
4848
new RestDocumentationContextPlaceholderResolverFactory();

0 commit comments

Comments
 (0)