diff --git a/docs/index.html b/docs/index.html index 8f837bb5..6e93b1de 100644 --- a/docs/index.html +++ b/docs/index.html @@ -467,6 +467,7 @@

Spring Auto REST Docs

  • Paging support
  • Preprocessors
  • Deprecation support
    • +
  • See tag support
  • Localization support
    • @@ -949,6 +950,19 @@

    +

    Configuration

    +
    +

    Configuration available during MockMvc setup:

    +
    +
    + +
    +

    Request parameters snippet

    @@ -1001,6 +1015,19 @@

    +

    Configuration

    +
    +

    Configuration available during MockMvc setup:

    +
    +
    +
      +
    • +

      failOnUndocumentedParams - if build should fail on at least one undocumented parameter

      +
      • +
    +
    +

    Request headers snippet

    @@ -1105,6 +1132,22 @@

    +
    +

    Configuration

    +
    +

    Configuration available during MockMvc setup:

    +
    +
    +
      +
    • +

      failOnUndocumentedFields - if build should fail on at least one undocumented field

      +
      • +
    • +

      requestBodyAsType - specified class should be considered as request type instead of endpoint method’s parameter

      +
      • +
    +
    +

    Response fields snippet

    @@ -1165,6 +1208,22 @@

    +

    Configuration

    +
    +

    Configuration available during MockMvc setup:

    +
    +
    +
      +
    • +

      failOnUndocumentedFields - if build should fail on at least one undocumented field

      +
      • +
    • +

      responseBodyAsType - specified class should be considered as response type instead of endpoint method’s return type

      +
      • +
    +
    +

    Section snippet

    @@ -1350,7 +1409,7 @@
    -

    If you use @title tag and want to generate regular Javadoc we well, +

    If you use @title tag and want to generate regular Javadoc as well, you need to include this tag among custom tags in plugin configuration.

    @@ -1671,12 +1730,20 @@

    Deprecation support

    -

    The deprecation is only visible when using Section approach. Then it will be shown in the title (also visible in -TOC) and description. Field’s deprecation is shown in description column of request/response table. +

    Deprecation is shown in the title of an endpoint (also visible in TOC) and description. +Field’s deprecation is shown in description column of request/response table.
    See how it looks in the example project.

    +

    See tag support

    +
    +

    @see Javadoc tag comment will be added to the main description section of an endpoint or a field.
    +Currently supports only HTML links. Does not support Java code references.
    +See how it looks in the example project.

    +
    +
    +

    Localization support

    For custom translations of section titles, table headers and other messages:

    @@ -1773,7 +1840,7 @@

    -Last updated 2018-01-06 21:38:23 CET +Last updated 2018-01-09 13:17:48 CET

    diff --git a/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/AutoDocumentation.java b/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/AutoDocumentation.java index e77323b0..b2dff519 100644 --- a/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/AutoDocumentation.java +++ b/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/AutoDocumentation.java @@ -43,23 +43,23 @@ public static JacksonResponseFieldSnippet responseFields() { return new JacksonResponseFieldSnippet(); } - public static Snippet pathParameters() { + public static PathParametersSnippet pathParameters() { return new PathParametersSnippet(); } - public static Snippet requestHeaders() { + public static RequestHeaderSnippet requestHeaders() { return new RequestHeaderSnippet(); } - public static Snippet requestParameters() { + public static RequestParametersSnippet requestParameters() { return new RequestParametersSnippet(); } - public static Snippet description() { + public static DescriptionSnippet description() { return new DescriptionSnippet(); } - public static Snippet methodAndPath() { + public static MethodAndPathSnippet methodAndPath() { return new MethodAndPathSnippet(); } diff --git a/spring-auto-restdocs-docs/other.adoc b/spring-auto-restdocs-docs/other.adoc index 912a8810..647b7812 100644 --- a/spring-auto-restdocs-docs/other.adoc +++ b/spring-auto-restdocs-docs/other.adoc @@ -2,6 +2,7 @@ :example-dir: {master-dir}/spring-auto-restdocs-example :core-package: {master-dir}//spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs :restdocs-package: https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs +:html-preview: https://htmlpreview.github.io/? [[other]] == Other @@ -33,9 +34,16 @@ Endpoint or field will be marked as deprecated if at least one of these is prese - method / field is annotated with `@Deprecated` - method's / field's Javadoc has `@deprecated` tag -The deprecation is only visible when using <> approach. Then it will be shown in the title (also visible in -TOC) and description. Field's deprecation is shown in description column of request/response table. -See how it looks in the link:https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html#resources-item-resource-test-clone-item[example project]. +Deprecation is shown in the title of an endpoint (also visible in TOC) and description. +Field's deprecation is shown in description column of request/response table. + +See how it looks in the link:{html-preview}{example-dir}/generated-docs/index.html#resources-item-resource-test-clone-item[example project]. + +[[see-tag]] +=== See tag support + +`@see` Javadoc tag comment will be added to the main description section of an endpoint or a field. + +Currently supports only HTML links. Does not support Java code references. + +See how it looks in the link:{html-preview}{example-dir}/generated-docs/index.html#resources-item-resource-test-search[example project]. [[localization]] === Localization support diff --git a/spring-auto-restdocs-docs/section-snippet.adoc b/spring-auto-restdocs-docs/section-snippet.adoc index 68a34551..4323d90a 100644 --- a/spring-auto-restdocs-docs/section-snippet.adoc +++ b/spring-auto-restdocs-docs/section-snippet.adoc @@ -125,7 +125,7 @@ AutoDocumentation.sectionBuilder() Section title uses text from `@title` Javadoc tag on the handler method. If missing, it's derived from the method name, e.g. `getItemById` -> _Get Item By Id_. -If you use `@title` tag and want to generate regular Javadoc we well, +If you use `@title` tag and want to generate regular Javadoc as well, you need to include this tag among custom tags in plugin configuration. .Custom maven-javadoc-plugin configuration diff --git a/spring-auto-restdocs-docs/snippets.adoc b/spring-auto-restdocs-docs/snippets.adoc index f97c9158..2ed302e9 100644 --- a/spring-auto-restdocs-docs/snippets.adoc +++ b/spring-auto-restdocs-docs/snippets.adoc @@ -111,6 +111,12 @@ public ItemResponse getItem(@PathVariable String id) { ... } |=== +==== Configuration + +Configuration available during MockMvc setup: + +- `failOnUndocumentedParams` - if build should fail on at least one undocumented parameter + [[snippets-request-parameters]] === Request parameters snippet @@ -148,6 +154,12 @@ Default value: "en". |=== +==== Configuration + +Configuration available during MockMvc setup: + +- `failOnUndocumentedParams` - if build should fail on at least one undocumented parameter + [[snippets-request-headers]] === Request headers snippet @@ -223,6 +235,13 @@ Size must be between 0 and 20 inclusive. |=== +==== Configuration + +Configuration available during MockMvc setup: + +- `failOnUndocumentedFields` - if build should fail on at least one undocumented field +- `requestBodyAsType` - specified class should be considered as request type instead of endpoint method's parameter + [[snippets-response-fields]] === Response fields snippet @@ -268,6 +287,13 @@ Must be at least 1. |=== +==== Configuration + +Configuration available during MockMvc setup: + +- `failOnUndocumentedFields` - if build should fail on at least one undocumented field +- `responseBodyAsType` - specified class should be considered as response type instead of endpoint method's return type + include::section-snippet.adoc[] [[snippets-custom]] diff --git a/spring-auto-restdocs-example/generated-docs/index.html b/spring-auto-restdocs-example/generated-docs/index.html index e4fd9295..d6b3c1e9 100644 --- a/spring-auto-restdocs-example/generated-docs/index.html +++ b/spring-auto-restdocs-example/generated-docs/index.html @@ -1122,7 +1122,7 @@ 

    $ curl 'http://localhost:8080/items' -i -X POST \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18' \
+    -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d' \
     -d '{"description":"Hot News"}'

    @@ -1359,7 +1359,7 @@ 

    $ curl 'http://localhost:8080/items/1' -i -X PUT \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18' \
+    -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d' \
     -d '{"description":"Hot News"}'
    @@ -1465,7 +1465,7 @@ 

    $ curl 'http://localhost:8080/items/1' -i -X DELETE \
-    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18'
    + -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d'
    @@ -1950,19 +1950,19 @@

    < "page" : 0, "size" : 20, "sort" : null, + "offset" : 0, "pageNumber" : 0, - "pageSize" : 20, - "offset" : 0 + "pageSize" : 20 }, "total" : 1, "totalPages" : 1, - "last" : true, "totalElements" : 1, + "last" : true, + "size" : 20, + "number" : 0, "sort" : null, - "first" : true, "numberOfElements" : 1, - "size" : 20, - "number" : 0 + "first" : true } @@ -2537,7 +2537,7 @@

    -Last updated 2018-01-06 21:26:54 CET +Last updated 2018-01-09 13:15:28 CET