├── .github ├── dco.yml ├── workflows │ ├── run-codeql-analysis.yml │ ├── delete-staged-release.yml │ ├── build-pull-request.yml │ └── trigger-docs-build.yml └── actions │ ├── sync-to-maven-central │ ├── artifacts.spec │ └── action.yml │ ├── print-jvm-thread-dumps │ └── action.yml │ ├── await-http-resource │ └── action.yml │ └── create-github-release │ ├── changelog-generator.yml │ └── action.yml ├── spring-restdocs-core ├── src │ ├── test │ │ ├── resources │ │ │ ├── field-payloads │ │ │ │ ├── no-fields.json │ │ │ │ ├── single-field.json │ │ │ │ ├── multiple-fields-and-embedded.json │ │ │ │ ├── multiple-fields-and-links.json │ │ │ │ ├── multiple-fields-and-embedded-and-links.json │ │ │ │ └── multiple-fields.json │ │ │ ├── link-payloads │ │ │ │ ├── atom │ │ │ │ │ ├── no-links.json │ │ │ │ │ ├── single-link.json │ │ │ │ │ ├── wrong-format.json │ │ │ │ │ ├── multiple-links-different-rels.json │ │ │ │ │ └── multiple-links-same-rels.json │ │ │ │ └── hal │ │ │ │ │ ├── no-links.json │ │ │ │ │ ├── single-link.json │ │ │ │ │ ├── wrong-format.json │ │ │ │ │ ├── multiple-links-different-rels.json │ │ │ │ │ └── multiple-links-same-rels.json │ │ │ ├── org │ │ │ │ └── springframework │ │ │ │ │ └── restdocs │ │ │ │ │ ├── templates │ │ │ │ │ ├── test-custom.snippet │ │ │ │ │ ├── test-default.snippet │ │ │ │ │ ├── multiple-snippets.snippet │ │ │ │ │ └── test-format-specific-custom.snippet │ │ │ │ │ └── constraints │ │ │ │ │ └── TestConstraintDescriptions.properties │ │ │ └── custom-snippet-templates │ │ │ │ ├── markdown │ │ │ │ ├── request-body-with-language.snippet │ │ │ │ ├── response-body-with-language.snippet │ │ │ │ ├── request-part-body-with-language.snippet │ │ │ │ ├── curl-request-with-title.snippet │ │ │ │ ├── httpie-request-with-title.snippet │ │ │ │ ├── links-with-title.snippet │ │ │ │ ├── request-cookies-with-title.snippet │ │ │ │ ├── request-headers-with-title.snippet │ │ │ │ ├── response-cookies-with-title.snippet │ │ │ │ ├── response-headers-with-title.snippet │ │ │ │ ├── links-with-extra-column.snippet │ │ │ │ ├── request-parts-with-title.snippet │ │ │ │ ├── request-cookies-with-extra-column.snippet │ │ │ │ ├── request-headers-with-extra-column.snippet │ │ │ │ ├── form-parameters-with-title.snippet │ │ │ │ ├── http-request-with-title.snippet │ │ │ │ ├── path-parameters-with-title.snippet │ │ │ │ ├── query-parameters-with-title.snippet │ │ │ │ ├── response-cookies-with-extra-column.snippet │ │ │ │ ├── response-headers-with-extra-column.snippet │ │ │ │ ├── request-parts-with-extra-column.snippet │ │ │ │ ├── response-fields-with-title.snippet │ │ │ │ ├── request-fields-with-title.snippet │ │ │ │ ├── form-parameters-with-extra-column.snippet │ │ │ │ ├── http-response-with-title.snippet │ │ │ │ ├── path-parameters-with-extra-column.snippet │ │ │ │ ├── query-parameters-with-extra-column.snippet │ │ │ │ ├── request-fields-with-extra-column.snippet │ │ │ │ ├── response-fields-with-extra-column.snippet │ │ │ │ ├── request-parts-with-optional-column.snippet │ │ │ │ ├── form-parameters-with-optional-column.snippet │ │ │ │ └── query-parameters-with-optional-column.snippet │ │ │ │ └── asciidoctor │ │ │ │ ├── request-body-with-language.snippet │ │ │ │ ├── response-body-with-language.snippet │ │ │ │ ├── curl-request-with-title.snippet │ │ │ │ ├── request-part-body-with-language.snippet │ │ │ │ ├── httpie-request-with-title.snippet │ │ │ │ ├── links-with-title.snippet │ │ │ │ ├── links-with-extra-column.snippet │ │ │ │ ├── request-cookies-with-title.snippet │ │ │ │ ├── request-headers-with-title.snippet │ │ │ │ ├── response-cookies-with-title.snippet │ │ │ │ ├── response-headers-with-title.snippet │ │ │ │ ├── request-parts-with-title.snippet │ │ │ │ ├── form-parameters-with-title.snippet │ │ │ │ ├── path-parameters-with-title.snippet │ │ │ │ ├── query-parameters-with-title.snippet │ │ │ │ ├── request-cookies-with-extra-column.snippet │ │ │ │ ├── request-headers-with-extra-column.snippet │ │ │ │ ├── response-cookies-with-extra-column.snippet │ │ │ │ ├── response-headers-with-extra-column.snippet │ │ │ │ ├── http-request-with-title.snippet │ │ │ │ ├── request-fields-with-title.snippet │ │ │ │ ├── request-parts-with-extra-column.snippet │ │ │ │ ├── response-fields-with-title.snippet │ │ │ │ ├── form-parameters-with-extra-column.snippet │ │ │ │ ├── path-parameters-with-extra-column.snippet │ │ │ │ ├── query-parameters-with-extra-column.snippet │ │ │ │ ├── request-fields-with-extra-column.snippet │ │ │ │ ├── response-fields-with-extra-column.snippet │ │ │ │ ├── form-parameters-with-optional-column.snippet │ │ │ │ ├── http-response-with-title.snippet │ │ │ │ ├── request-parts-with-optional-column.snippet │ │ │ │ ├── query-parameters-with-optional-column.snippet │ │ │ │ └── request-fields-with-list-description.snippet │ │ └── java │ │ │ └── org │ │ │ └── springframework │ │ │ └── restdocs │ │ │ └── hypermedia │ │ │ └── StubLinkExtractor.java │ ├── main │ │ ├── resources │ │ │ └── org │ │ │ │ └── springframework │ │ │ │ └── restdocs │ │ │ │ └── templates │ │ │ │ ├── markdown │ │ │ │ ├── default-curl-request.snippet │ │ │ │ ├── default-request-body.snippet │ │ │ │ ├── default-request-part-body.snippet │ │ │ │ ├── default-response-body.snippet │ │ │ │ ├── default-httpie-request.snippet │ │ │ │ ├── default-links.snippet │ │ │ │ ├── default-request-headers.snippet │ │ │ │ ├── default-response-headers.snippet │ │ │ │ ├── default-request-cookies.snippet │ │ │ │ ├── default-response-cookies.snippet │ │ │ │ ├── default-request-parts.snippet │ │ │ │ ├── default-form-parameters.snippet │ │ │ │ ├── default-http-request.snippet │ │ │ │ ├── default-query-parameters.snippet │ │ │ │ ├── default-request-parameters.snippet │ │ │ │ ├── default-request-fields.snippet │ │ │ │ ├── default-response-fields.snippet │ │ │ │ ├── default-http-response.snippet │ │ │ │ ├── default-request-part-fields.snippet │ │ │ │ └── default-path-parameters.snippet │ │ │ │ └── asciidoctor │ │ │ │ ├── default-curl-request.snippet │ │ │ │ ├── default-httpie-request.snippet │ │ │ │ ├── default-request-body.snippet │ │ │ │ ├── default-response-body.snippet │ │ │ │ ├── default-request-part-body.snippet │ │ │ │ ├── default-http-request.snippet │ │ │ │ ├── default-http-response.snippet │ │ │ │ ├── default-links.snippet │ │ │ │ ├── default-request-cookies.snippet │ │ │ │ ├── default-request-headers.snippet │ │ │ │ ├── default-response-cookies.snippet │ │ │ │ ├── default-response-headers.snippet │ │ │ │ ├── default-request-parts.snippet │ │ │ │ ├── default-form-parameters.snippet │ │ │ │ ├── default-query-parameters.snippet │ │ │ │ ├── default-request-parameters.snippet │ │ │ │ ├── default-path-parameters.snippet │ │ │ │ ├── default-request-fields.snippet │ │ │ │ ├── default-response-fields.snippet │ │ │ │ └── default-request-part-fields.snippet │ │ └── java │ │ │ └── org │ │ │ └── springframework │ │ │ └── restdocs │ │ │ ├── package-info.java │ │ │ ├── snippet │ │ │ ├── package-info.java │ │ │ ├── SnippetException.java │ │ │ ├── Snippet.java │ │ │ ├── PlaceholderResolverFactory.java │ │ │ ├── RestDocumentationContextPlaceholderResolverFactory.java │ │ │ ├── ModelCreationException.java │ │ │ ├── IgnorableDescriptor.java │ │ │ └── WriterResolver.java │ │ │ ├── config │ │ │ ├── package-info.java │ │ │ ├── NestedConfigurer.java │ │ │ ├── SnippetConfiguration.java │ │ │ ├── AbstractConfigurer.java │ │ │ └── AbstractNestedConfigurer.java │ │ │ ├── constraints │ │ │ ├── package-info.java │ │ │ ├── ConstraintDescriptionResolver.java │ │ │ ├── ConstraintResolver.java │ │ │ └── Constraint.java │ │ │ ├── hypermedia │ │ │ ├── package-info.java │ │ │ ├── LinkExtractor.java │ │ │ └── AbstractJsonLinkExtractor.java │ │ │ ├── templates │ │ │ ├── package-info.java │ │ │ ├── mustache │ │ │ │ ├── package-info.java │ │ │ │ └── AsciidoctorTableCellContentLambda.java │ │ │ ├── Template.java │ │ │ ├── TemplateFormat.java │ │ │ ├── TemplateResourceResolver.java │ │ │ └── TemplateEngine.java │ │ │ ├── cli │ │ │ ├── package-info.java │ │ │ └── CommandFormatter.java │ │ │ ├── cookies │ │ │ └── package-info.java │ │ │ ├── generate │ │ │ ├── package-info.java │ │ │ └── RestDocumentationGenerationException.java │ │ │ ├── headers │ │ │ └── package-info.java │ │ │ ├── payload │ │ │ ├── package-info.java │ │ │ ├── SubsectionDescriptor.java │ │ │ ├── FieldTypeRequiredException.java │ │ │ ├── FieldDoesNotExistException.java │ │ │ ├── PayloadHandlingException.java │ │ │ ├── FieldTypesDoNotMatchException.java │ │ │ ├── JsonFieldType.java │ │ │ └── JsonFieldTypes.java │ │ │ ├── request │ │ │ └── package-info.java │ │ │ ├── http │ │ │ └── package-info.java │ │ │ ├── operation │ │ │ ├── preprocess │ │ │ │ ├── package-info.java │ │ │ │ ├── HeaderFilter.java │ │ │ │ ├── OperationRequestPreprocessor.java │ │ │ │ ├── OperationResponsePreprocessor.java │ │ │ │ ├── ExactMatchHeaderFilter.java │ │ │ │ ├── PatternMatchHeaderFilter.java │ │ │ │ ├── OperationPreprocessor.java │ │ │ │ └── ContentModifier.java │ │ │ ├── package-info.java │ │ │ ├── OperationMessage.java │ │ │ ├── RequestConverter.java │ │ │ ├── ResponseConverter.java │ │ │ ├── Operation.java │ │ │ ├── RequestCookie.java │ │ │ ├── ResponseCookie.java │ │ │ └── ConversionException.java │ │ │ ├── RestDocumentationContextProvider.java │ │ │ └── RestDocumentationContext.java │ └── testFixtures │ │ └── java │ │ └── org │ │ └── springframework │ │ └── restdocs │ │ └── testfixtures │ │ └── jupiter │ │ ├── SnippetTemplate.java │ │ └── SnippetTest.java └── build.gradle ├── .sdkmanrc ├── gradle ├── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties └── plugins │ ├── optional-dependencies │ ├── src │ │ └── main │ │ │ └── resources │ │ │ └── META-INF │ │ │ └── gradle-plugins │ │ │ └── optional-dependencies.properties │ └── build.gradle │ ├── toolchain │ ├── build.gradle │ └── src │ │ └── main │ │ └── java │ │ └── org │ │ └── springframework │ │ └── restdocs │ │ └── build │ │ └── toolchain │ │ ├── package-info.java │ │ └── ToolchainPlugin.java │ ├── config │ └── checkstyle │ │ └── checkstyle.xml │ ├── antora │ ├── src │ │ └── main │ │ │ └── resources │ │ │ └── antora-playbook-template.yml │ └── build.gradle │ ├── settings.gradle │ ├── conventions │ ├── build.gradle │ └── src │ │ └── main │ │ └── java │ │ └── org │ │ └── springframework │ │ └── restdocs │ │ └── build │ │ └── conventions │ │ ├── ConventionsPlugin.java │ │ └── Conventions.java │ └── build.gradle ├── spring-restdocs-docs └── src │ ├── docs │ └── antora │ │ ├── modules │ │ ├── api │ │ │ └── partials │ │ │ │ └── nav-api.adoc │ │ ├── tutorial │ │ │ ├── partials │ │ │ │ └── nav-tutorial.adoc │ │ │ └── pages │ │ │ │ └── index.adoc │ │ ├── reference │ │ │ ├── pages │ │ │ │ ├── index.adoc │ │ │ │ ├── configuration │ │ │ │ │ ├── index.adoc │ │ │ │ │ ├── snippet-template-format.adoc │ │ │ │ │ ├── default-snippets.adoc │ │ │ │ │ ├── snippet-encoding.adoc │ │ │ │ │ ├── default-preprocessors.adoc │ │ │ │ │ └── uris.adoc │ │ │ │ ├── documenting-your-api │ │ │ │ │ ├── index.adoc │ │ │ │ │ ├── null-safety.adoc │ │ │ │ │ └── default-snippets.adoc │ │ │ │ └── working-with-markdown.adoc │ │ │ └── partials │ │ │ │ └── nav-reference.adoc │ │ ├── ROOT │ │ │ └── pages │ │ │ │ ├── system-requirements.adoc │ │ │ │ ├── contributing.adoc │ │ │ │ └── index.adoc │ │ └── how-to │ │ │ ├── partials │ │ │ └── nav-how-to.adoc │ │ │ └── pages │ │ │ ├── index.adoc │ │ │ └── reusing-snippets.adoc │ │ ├── nav.adoc │ │ └── antora.yml │ └── test │ └── java │ └── org │ └── springframework │ └── restdocs │ └── docs │ ├── documentingyourapi │ ├── requestresponsepayloads │ │ ├── subsections │ │ │ └── body │ │ │ │ └── CustomSubsectionId.java │ │ └── fields │ │ │ └── reusingfielddescriptors │ │ │ └── BookPayload.java │ ├── constraints │ │ └── Constraints.java │ └── hypermedia │ │ └── ignoringcommonlinks │ │ └── Hypermedia.java │ ├── gettingstarted │ └── documentationsnippets │ │ └── invokingtheservice │ │ ├── webtestclient │ │ └── InvokeService.java │ │ └── mockmvc │ │ └── InvokeService.java │ └── howto │ └── reusingsnippets │ └── CommonSnippets.java ├── spring-restdocs-mockmvc ├── src │ ├── test │ │ └── resources │ │ │ ├── custom-snippet-templates │ │ │ └── org │ │ │ │ └── springframework │ │ │ │ └── restdocs │ │ │ │ └── templates │ │ │ │ └── curl-request.snippet │ │ │ └── org │ │ │ └── springframework │ │ │ └── restdocs │ │ │ └── templates │ │ │ └── request-parts.snippet │ └── main │ │ └── java │ │ └── org │ │ └── springframework │ │ └── restdocs │ │ └── mockmvc │ │ └── package-info.java └── build.gradle ├── spring-restdocs-asciidoctor ├── src │ ├── test │ │ ├── resources │ │ │ ├── some-operation │ │ │ │ ├── curl-request.adoc │ │ │ │ ├── custom-snippet.adoc │ │ │ │ ├── http-request.adoc │ │ │ │ └── response-fields.adoc │ │ │ ├── META-INF │ │ │ │ └── services │ │ │ │ │ └── org.asciidoctor.log.LogHandler │ │ │ ├── sample-snippet.adoc │ │ │ └── operations │ │ │ │ ├── missing-operation.html │ │ │ │ ├── missing-snippet.html │ │ │ │ ├── snippet-with-level.html │ │ │ │ ├── snippet-simple.html │ │ │ │ ├── custom-snippet-custom-title.html │ │ │ │ ├── custom-snippet-default-title.html │ │ │ │ ├── built-in-snippet-custom-title.html │ │ │ │ ├── multiple-snippets.html │ │ │ │ ├── snippet-in-section.html │ │ │ │ └── snippet-table.html │ │ └── java │ │ │ └── org │ │ │ └── springframework │ │ │ └── restdocs │ │ │ └── asciidoctor │ │ │ └── CapturingLogHandler.java │ └── main │ │ ├── resources │ │ └── META-INF │ │ │ └── services │ │ │ └── org.asciidoctor.jruby.extension.spi.ExtensionRegistry │ │ └── java │ │ └── org │ │ └── springframework │ │ └── restdocs │ │ └── asciidoctor │ │ ├── package-info.java │ │ ├── RestDocsExtensionRegistry.java │ │ └── DefaultAttributesPreprocessor.java └── build.gradle ├── .gitignore ├── gradle.properties ├── config └── checkstyle │ ├── checkstyle-suppressions.xml │ └── checkstyle.xml ├── spring-restdocs-bom └── build.gradle ├── settings.gradle ├── spring-restdocs-webtestclient ├── build.gradle └── src │ └── main │ └── java │ └── org │ └── springframework │ └── restdocs │ └── webtestclient │ └── package-info.java ├── antora └── package.json └── spring-restdocs-platform └── build.gradle /.github/dco.yml: -------------------------------------------------------------------------------- 1 | require: 2 | members: false 3 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/no-fields.json: -------------------------------------------------------------------------------- 1 | { } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/atom/no-links.json: -------------------------------------------------------------------------------- 1 | { } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/hal/no-links.json: -------------------------------------------------------------------------------- 1 | { } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/org/springframework/restdocs/templates/test-custom.snippet: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/org/springframework/restdocs/templates/test-default.snippet: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/single-field.json: -------------------------------------------------------------------------------- 1 | { 2 | "alpha": "alpha-value" 3 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/org/springframework/restdocs/templates/multiple-snippets.snippet: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/org/springframework/restdocs/templates/test-format-specific-custom.snippet: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.sdkmanrc: -------------------------------------------------------------------------------- 1 | # Enable auto-env through the sdkman_auto_env config 2 | # Add key=value pairs of SDKs to use below 3 | java=25-librca 4 | -------------------------------------------------------------------------------- /gradle/wrapper/gradle-wrapper.jar: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/spring-projects/spring-restdocs/HEAD/gradle/wrapper/gradle-wrapper.jar -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | ```{{language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | ```{{language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/api/partials/nav-api.adoc: -------------------------------------------------------------------------------- 1 | * API 2 | ** xref:api:java/index.html[Java,role=link-external, window=_blank] -------------------------------------------------------------------------------- /spring-restdocs-mockmvc/src/test/resources/custom-snippet-templates/org/springframework/restdocs/templates/curl-request.snippet: -------------------------------------------------------------------------------- 1 | Custom curl request -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/some-operation/curl-request.adoc: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | ---- 3 | $ curl 'http://localhost:8080/' -i 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/some-operation/custom-snippet.adoc: -------------------------------------------------------------------------------- 1 | [source,http,options="nowrap"] 2 | ---- 3 | mycustomsnippet-äöü 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-part-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | ```{{language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/META-INF/services/org.asciidoctor.log.LogHandler: -------------------------------------------------------------------------------- 1 | org.springframework.restdocs.asciidoctor.CapturingLogHandler -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-curl-request.snippet: -------------------------------------------------------------------------------- 1 | ```bash 2 | $ curl {{url}} {{options}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/tutorial/partials/nav-tutorial.adoc: -------------------------------------------------------------------------------- 1 | * xref:tutorial:index.adoc[] 2 | ** xref:tutorial:getting-started/index.adoc[] 3 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/curl-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | ```bash 3 | $ curl {{url}} {{options}} 4 | ``` -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/sample-snippet.adoc: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | ---- 3 | $ curl 'http://localhost:8080/' -i -H 'Accept: application/hal+json' 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/tutorial/pages/index.adoc: -------------------------------------------------------------------------------- 1 | = Tutorials 2 | 3 | This section provides tutorials to help you begin to use Spring REST Docs. 4 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/missing-operation.html: -------------------------------------------------------------------------------- 1 |
2 |

No snippets found for operation::missing-operation

3 |
-------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/some-operation/http-request.adoc: -------------------------------------------------------------------------------- 1 | [source,http,options="nowrap"] 2 | ---- 3 | GET / HTTP/1.1 4 | Host: localhost:8080 5 | 6 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-body.snippet: -------------------------------------------------------------------------------- 1 | ```{{#language}}{{language}}{{/language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-curl-request.snippet: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | ---- 3 | $ curl {{url}} {{options}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-part-body.snippet: -------------------------------------------------------------------------------- 1 | ```{{#language}}{{language}}{{/language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-response-body.snippet: -------------------------------------------------------------------------------- 1 | ```{{#language}}{{language}}{{/language}} 2 | {{body}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | [source,{{language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | [source,{{language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/curl-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | .{{title}} 3 | ---- 4 | $ curl {{url}} {{options}} 5 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-part-body-with-language.snippet: -------------------------------------------------------------------------------- 1 | [source,{{language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/org/springframework/restdocs/constraints/TestConstraintDescriptions.properties: -------------------------------------------------------------------------------- 1 | jakarta.validation.constraints.NotNull.description=Should not be null -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry: -------------------------------------------------------------------------------- 1 | org.springframework.restdocs.asciidoctor.RestDocsExtensionRegistry 2 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/multiple-fields-and-embedded.json: -------------------------------------------------------------------------------- 1 | { 2 | "_embedded": "embedded-test", 3 | "beta": "beta-value", 4 | "charlie": "charlie-value" 5 | } -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/index.adoc: -------------------------------------------------------------------------------- 1 | = Reference 2 | 3 | This section provides information on using the features and capabilities of Spring REST Docs. 4 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-httpie-request.snippet: -------------------------------------------------------------------------------- 1 | ```bash 2 | $ {{echoContent}}http {{options}} {{url}}{{requestItems}} 3 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/httpie-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | ```bash 3 | $ {{echoContent}}http {{options}} {{url}}{{requestItems}} 4 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/atom/single-link.json: -------------------------------------------------------------------------------- 1 | { 2 | "links": [ { 3 | "rel": "alpha", 4 | "href": "https://alpha.example.com", 5 | "title": "Alpha" 6 | } ] 7 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/hal/single-link.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": { 3 | "alpha": { 4 | "href": "https://alpha.example.com", 5 | "title": "Alpha" 6 | } 7 | } 8 | } -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .classpath 2 | .gradle 3 | .project 4 | .settings 5 | bin 6 | build 7 | !buildSrc/src/main/groovy/org/springframework/restdocs/build/ 8 | target 9 | .idea/* 10 | !.idea/icon.svg 11 | *.iml -------------------------------------------------------------------------------- /gradle/plugins/optional-dependencies/src/main/resources/META-INF/gradle-plugins/optional-dependencies.properties: -------------------------------------------------------------------------------- 1 | implementation-class:org.springframework.restdocs.build.optional.OptionalDependenciesPlugin 2 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-httpie-request.snippet: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | ---- 3 | $ {{echoContent}}http {{options}} {{url}}{{requestItems}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-body.snippet: -------------------------------------------------------------------------------- 1 | [source{{#language}},{{language}}{{/language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-response-body.snippet: -------------------------------------------------------------------------------- 1 | [source{{#language}},{{language}}{{/language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/httpie-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | [source,bash] 2 | .{{title}} 3 | ---- 4 | $ {{echoContent}}http {{options}} {{url}}{{requestItems}} 5 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-part-body.snippet: -------------------------------------------------------------------------------- 1 | [source{{#language}},{{language}}{{/language}},options="nowrap"] 2 | ---- 3 | {{body}} 4 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-links.snippet: -------------------------------------------------------------------------------- 1 | Relation | Description 2 | -------- | ----------- 3 | {{#links}} 4 | `{{rel}}` | {{description}} 5 | {{/links}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/links-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Relation | Description 3 | -------- | ----------- 4 | {{#links}} 5 | {{rel}} | {{description}} 6 | {{/links}} -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/index.adoc: -------------------------------------------------------------------------------- 1 | [[configuration]] 2 | = Configuring Spring REST Docs 3 | 4 | This section provides information about configuring Spring REST Docs. 5 | -------------------------------------------------------------------------------- /gradle.properties: -------------------------------------------------------------------------------- 1 | version=4.0.1-SNAPSHOT 2 | 3 | org.gradle.caching=true 4 | org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8 5 | org.gradle.parallel=true 6 | 7 | javaFormatVersion=0.0.47 8 | springFrameworkVersion=7.0.0 9 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-headers.snippet: -------------------------------------------------------------------------------- 1 | Name | Description 2 | ---- | ----------- 3 | {{#headers}} 4 | `{{name}}` | {{description}} 5 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-response-headers.snippet: -------------------------------------------------------------------------------- 1 | Name | Description 2 | ---- | ----------- 3 | {{#headers}} 4 | `{{name}}` | {{description}} 5 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-cookies-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Name | Description 3 | ---- | ----------- 4 | {{#cookies}} 5 | {{name}} | {{description}} 6 | {{/cookies}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-headers-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Name | Description 3 | ---- | ----------- 4 | {{#headers}} 5 | {{name}} | {{description}} 6 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-cookies.snippet: -------------------------------------------------------------------------------- 1 | Name | Description 2 | ---- | ----------- 3 | {{#cookies}} 4 | `{{name}}` | {{description}} 5 | {{/cookies}} 6 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-response-cookies.snippet: -------------------------------------------------------------------------------- 1 | Name | Description 2 | ---- | ----------- 3 | {{#cookies}} 4 | `{{name}}` | {{description}} 5 | {{/cookies}} 6 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-cookies-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Name | Description 3 | ---- | ----------- 4 | {{#cookies}} 5 | {{name}} | {{description}} 6 | {{/cookies}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-headers-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Name | Description 3 | ---- | ----------- 4 | {{#headers}} 5 | {{name}} | {{description}} 6 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-parts.snippet: -------------------------------------------------------------------------------- 1 | Part | Description 2 | ---- | ----------- 3 | {{#requestParts}} 4 | `{{name}}` | {{description}} 5 | {{/requestParts}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/links-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Relation | Description | Foo 2 | -------- | ----------- | --- 3 | {{#links}} 4 | {{rel}} | {{description}} | {{foo}} 5 | {{/links}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-parts-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Part | Description 3 | ---- | ----------- 4 | {{#requestParts}} 5 | {{name}} | {{description}} 6 | {{/requestParts}} -------------------------------------------------------------------------------- /spring-restdocs-mockmvc/src/test/resources/org/springframework/restdocs/templates/request-parts.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Request part|Description 3 | 4 | {{#requestParts}} 5 | |`{{name}}` 6 | |{{description}} 7 | 8 | {{/requestParts}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-form-parameters.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description 2 | --------- | ----------- 3 | {{#parameters}} 4 | `{{name}}` | {{description}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-http-request.snippet: -------------------------------------------------------------------------------- 1 | ```http 2 | {{method}} {{path}} HTTP/1.1 3 | {{#headers}} 4 | {{name}}: {{value}} 5 | {{/headers}} 6 | {{requestBody}} 7 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/links-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Relation|Description 4 | 5 | {{#links}} 6 | |{{rel}} 7 | |{{description}} 8 | 9 | {{/links}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-cookies-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Name | Description | Foo 2 | ---- | ----------- | --- 3 | {{#cookies}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/cookies}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-headers-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Name | Description | Foo 2 | ---- | ----------- | --- 3 | {{#headers}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/index.adoc: -------------------------------------------------------------------------------- 1 | [[documenting-your-api]] 2 | = Documenting your API 3 | 4 | This section provides more details about using Spring REST Docs to document your API. 5 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-query-parameters.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description 2 | --------- | ----------- 3 | {{#parameters}} 4 | `{{name}}` | {{description}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-parameters.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description 2 | --------- | ----------- 3 | {{#parameters}} 4 | `{{name}}` | {{description}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/links-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Relation|Description|Foo 3 | 4 | {{#links}} 5 | |{{rel}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/links}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/form-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Parameter | Description 3 | --------- | ----------- 4 | {{#parameters}} 5 | {{name}} | {{description}} 6 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/http-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | ```http 3 | {{method}} {{path}} HTTP/1.1 4 | {{#headers}} 5 | {{name}}: {{value}} 6 | {{/headers}} 7 | {{requestBody}} 8 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/path-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Parameter | Description 3 | --------- | ----------- 4 | {{#parameters}} 5 | {{name}} | {{description}} 6 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/query-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Parameter | Description 3 | --------- | ----------- 4 | {{#parameters}} 5 | {{name}} | {{description}} 6 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-cookies-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Name | Description | Foo 2 | ---- | ----------- | --- 3 | {{#cookies}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/cookies}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-headers-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Name | Description | Foo 2 | ---- | ----------- | --- 3 | {{#headers}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/headers}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/atom/wrong-format.json: -------------------------------------------------------------------------------- 1 | { 2 | "links": { 3 | "alpha": [{ 4 | "href": "https://alpha.example.com/one" 5 | }, { 6 | "href": "https://alpha.example.com/two" 7 | }] 8 | } 9 | } -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/ROOT/pages/system-requirements.adoc: -------------------------------------------------------------------------------- 1 | [[system-requirements]] 2 | = System Requirements 3 | 4 | Spring REST Docs has the following minimum requirements: 5 | 6 | * Java 17 7 | * Spring Framework 7 8 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-fields.snippet: -------------------------------------------------------------------------------- 1 | Path | Type | Description 2 | ---- | ---- | ----------- 3 | {{#fields}} 4 | `{{path}}` | `{{type}}` | {{description}} 5 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-response-fields.snippet: -------------------------------------------------------------------------------- 1 | Path | Type | Description 2 | ---- | ---- | ----------- 3 | {{#fields}} 4 | `{{path}}` | `{{type}}` | {{description}} 5 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-cookies-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Name|Description 4 | 5 | {{#cookies}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/cookies}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-headers-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Name|Description 4 | 5 | {{#headers}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/headers}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-cookies-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Name|Description 4 | 5 | {{#cookies}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/cookies}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-headers-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Name|Description 4 | 5 | {{#headers}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/headers}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-parts-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Part | Description | Foo 2 | ---- | ----------- | --- 3 | {{#requestParts}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/requestParts}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-fields-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | Path | Type | Description 3 | ---- | ---- | ----------- 4 | {{#fields}} 5 | {{path}} | {{type}} | {{description}} 6 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-http-response.snippet: -------------------------------------------------------------------------------- 1 | ```http 2 | HTTP/1.1 {{statusCode}} {{statusReason}} 3 | {{#headers}} 4 | {{name}}: {{value}} 5 | {{/headers}} 6 | {{responseBody}} 7 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-request-part-fields.snippet: -------------------------------------------------------------------------------- 1 | Path | Type | Description 2 | ---- | ---- | ----------- 3 | {{#fields}} 4 | `{{path}}` | `{{type}}` | {{description}} 5 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-parts-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Part|Description 4 | 5 | {{#requestParts}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/requestParts}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-fields-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | 3 | Path | Type | Description 4 | ---- | ---- | ----------- 5 | {{#fields}} 6 | {{path}} | {{type}} | {{description}} 7 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/hal/wrong-format.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": [ { 3 | "rel": "alpha", 4 | "href": "https://alpha.example.com/one" 5 | }, { 6 | "rel": "alpha", 7 | "href": "https://alpha.example.com/two" 8 | } ] 9 | } -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/some-operation/response-fields.adoc: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description 3 | 4 | |`a` 5 | |`Object` 6 | |one 7 | 8 | |`a.b` 9 | |`Number` 10 | |two 11 | 12 | |`a.c` 13 | |`String` 14 | |three 15 | 16 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/markdown/default-path-parameters.snippet: -------------------------------------------------------------------------------- 1 | `{{path}}` 2 | 3 | Parameter | Description 4 | --------- | ----------- 5 | {{#parameters}} 6 | `{{name}}` | {{description}} 7 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/form-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Parameter|Description 4 | 5 | {{#parameters}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/path-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Parameter|Description 4 | 5 | {{#parameters}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/query-parameters-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Parameter|Description 4 | 5 | {{#parameters}} 6 | |{{name}} 7 | |{{description}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-cookies-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description|Foo 3 | 4 | {{#cookies}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/cookies}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-headers-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description|Foo 3 | 4 | {{#headers}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/headers}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-cookies-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description|Foo 3 | 4 | {{#cookies}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/cookies}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-headers-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description|Foo 3 | 4 | {{#headers}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/headers}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/form-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description | Foo 2 | --------- | ----------- | --- 3 | {{#parameters}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/http-response-with-title.snippet: -------------------------------------------------------------------------------- 1 | {{title}} 2 | ```http 3 | HTTP/1.1 {{statusCode}} {{statusReason}} 4 | {{#headers}} 5 | {{name}}: {{value}} 6 | {{/headers}} 7 | {{responseBody}} 8 | ``` -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/path-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description | Foo 2 | --------- | ----------- | --- 3 | {{#parameters}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/query-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Description | Foo 2 | --------- | ----------- | --- 3 | {{#parameters}} 4 | {{name}} | {{description}} | {{foo}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/multiple-fields-and-links.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": { 3 | "alpha": "https://alpha.example.com", 4 | "bravo": "https://bravo.example.com" 5 | }, 6 | "beta": "beta-value", 7 | "charlie": "charlie-value" 8 | } -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/how-to/partials/nav-how-to.adoc: -------------------------------------------------------------------------------- 1 | * xref:how-to:index.adoc[] 2 | ** xref:how-to:reusing-snippets.adoc[] 3 | ** xref:how-to:parameterizing-the-output-directory.adoc[] 4 | ** xref:how-to:customizing-the-output.adoc[] 5 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/http-request-with-title.snippet: -------------------------------------------------------------------------------- 1 | [source,http] 2 | .{{title}} 3 | ---- 4 | {{method}} {{path}} HTTP/1.1 5 | {{#headers}} 6 | {{name}}: {{value}} 7 | {{/headers}} 8 | {{requestBody}} 9 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-fields-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Path|Type|Description 4 | 5 | {{#fields}} 6 | |{{path}} 7 | |{{type}} 8 | |{{description}} 9 | 10 | {{/fields}} 11 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-parts-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Part|Description|Foo 3 | 4 | {{#requestParts}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/requestParts}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-fields-with-title.snippet: -------------------------------------------------------------------------------- 1 | .{{title}} 2 | |=== 3 | |Path|Type|Description 4 | 5 | {{#fields}} 6 | |{{path}} 7 | |{{type}} 8 | |{{description}} 9 | 10 | {{/fields}} 11 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-fields-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Path | Type | Description | Foo 2 | ---- | ---- | ----------- | --- 3 | {{#fields}} 4 | {{path}} | {{type}} | {{description}} | {{foo}} 5 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-fields-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | Path | Type | Description | Foo 2 | ---- | ---- | ----------- | --- 3 | {{#fields}} 4 | {{path}} | {{type}} | {{description}} | {{foo}} 5 | {{/fields}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/form-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description|Foo 3 | 4 | {{#parameters}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/path-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description|Foo 3 | 4 | {{#parameters}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/query-parameters-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description|Foo 3 | 4 | {{#parameters}} 5 | |{{name}} 6 | |{{description}} 7 | |{{foo}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-parts-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | Part | Optional | Description 2 | ---- | -------- | ----------- 3 | {{#requestParts}} 4 | {{name}} | {{optional}} | {{description}} 5 | {{/requestParts}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-http-request.snippet: -------------------------------------------------------------------------------- 1 | [source,http,options="nowrap"] 2 | ---- 3 | {{method}} {{path}} HTTP/1.1 4 | {{#headers}} 5 | {{name}}: {{value}} 6 | {{/headers}} 7 | {{requestBody}} 8 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-fields-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description|Foo 3 | 4 | {{#fields}} 5 | |{{path}} 6 | |{{type}} 7 | |{{description}} 8 | |{{foo}} 9 | 10 | {{/fields}} 11 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-fields-with-extra-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description|Foo 3 | 4 | {{#fields}} 5 | |{{path}} 6 | |{{type}} 7 | |{{description}} 8 | |{{foo}} 9 | 10 | {{/fields}} 11 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/form-parameters-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Optional | Description 2 | --------- | -------- | ----------- 3 | {{#parameters}} 4 | {{name}} | {{optional}} | {{description}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/query-parameters-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | Parameter | Optional | Description 2 | --------- | -------- | ----------- 3 | {{#parameters}} 4 | {{name}} | {{optional}} | {{description}} 5 | {{/parameters}} -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/form-parameters-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Optional|Description 3 | 4 | {{#parameters}} 5 | |{{name}} 6 | |{{optional}} 7 | |{{description}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/http-response-with-title.snippet: -------------------------------------------------------------------------------- 1 | [source,http] 2 | .{{title}} 3 | ---- 4 | HTTP/1.1 {{statusCode}} {{statusReason}} 5 | {{#headers}} 6 | {{name}}: {{value}} 7 | {{/headers}} 8 | {{responseBody}} 9 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-parts-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Part|Optional|Description 3 | 4 | {{#requestParts}} 5 | |{{name}} 6 | |{{optional}} 7 | |{{description}} 8 | 9 | {{/requestParts}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/query-parameters-with-optional-column.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Optional|Description 3 | 4 | {{#parameters}} 5 | |{{name}} 6 | |{{optional}} 7 | |{{description}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-http-response.snippet: -------------------------------------------------------------------------------- 1 | [source,http,options="nowrap"] 2 | ---- 3 | HTTP/1.1 {{statusCode}} {{statusReason}} 4 | {{#headers}} 5 | {{name}}: {{value}} 6 | {{/headers}} 7 | {{responseBody}} 8 | ---- -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/hal/multiple-links-different-rels.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": { 3 | "alpha": { 4 | "href": "https://alpha.example.com", 5 | "title": "Alpha" 6 | }, 7 | "bravo": { 8 | "href": "https://bravo.example.com" 9 | } 10 | } 11 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/hal/multiple-links-same-rels.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": { 3 | "alpha": [{ 4 | "href": "https://alpha.example.com/one", 5 | "title": "Alpha one" 6 | }, { 7 | "href": "https://alpha.example.com/two" 8 | }] 9 | } 10 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/atom/multiple-links-different-rels.json: -------------------------------------------------------------------------------- 1 | { 2 | "links": [ { 3 | "rel": "alpha", 4 | "href": "https://alpha.example.com", 5 | "title": "Alpha" 6 | }, { 7 | "rel": "bravo", 8 | "href": "https://bravo.example.com" 9 | } ] 10 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/link-payloads/atom/multiple-links-same-rels.json: -------------------------------------------------------------------------------- 1 | { 2 | "links": [ { 3 | "rel": "alpha", 4 | "href": "https://alpha.example.com/one", 5 | "title": "Alpha one" 6 | }, { 7 | "rel": "alpha", 8 | "href": "https://alpha.example.com/two" 9 | } ] 10 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-links.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Relation|Description 3 | 4 | {{#links}} 5 | |{{#tableCellContent}}`+{{rel}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/links}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/multiple-fields-and-embedded-and-links.json: -------------------------------------------------------------------------------- 1 | { 2 | "_links": { 3 | "alpha": "https://alpha.example.com", 4 | "bravo": "https://bravo.example.com" 5 | }, 6 | "_embedded": "embedded-test", 7 | "beta": "beta-value", 8 | "charlie": "charlie-value" 9 | } -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/missing-snippet.html: -------------------------------------------------------------------------------- 1 |
2 |

Missing snippet

3 |
4 |
5 |

Snippet missing-snippet not found for operation::some-operation

6 |
7 |
8 |
-------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-fields-with-list-description.snippet: -------------------------------------------------------------------------------- 1 | [cols="1,1,1a"] 2 | |=== 3 | |Path|Type|Description 4 | 5 | {{#fields}} 6 | |{{path}} 7 | |{{type}} 8 | |{{#description}} - {{.}} 9 | {{/description}} 10 | 11 | {{/fields}} 12 | |=== -------------------------------------------------------------------------------- /gradle/wrapper/gradle-wrapper.properties: -------------------------------------------------------------------------------- 1 | distributionBase=GRADLE_USER_HOME 2 | distributionPath=wrapper/dists 3 | distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip 4 | networkTimeout=10000 5 | validateDistributionUrl=true 6 | zipStoreBase=GRADLE_USER_HOME 7 | zipStorePath=wrapper/dists 8 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/nav.adoc: -------------------------------------------------------------------------------- 1 | * xref:index.adoc[] 2 | * xref:system-requirements.adoc[] 3 | include::tutorial:partial$nav-tutorial.adoc[] 4 | include::reference:partial$nav-reference.adoc[] 5 | include::how-to:partial$nav-how-to.adoc[] 6 | include::api:partial$nav-api.adoc[] 7 | * xref:contributing.adoc[] -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-cookies.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description 3 | 4 | {{#cookies}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/cookies}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-headers.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description 3 | 4 | {{#headers}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/headers}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-response-cookies.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description 3 | 4 | {{#cookies}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/cookies}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-response-headers.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Name|Description 3 | 4 | {{#headers}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/headers}} 9 | |=== -------------------------------------------------------------------------------- /gradle/plugins/toolchain/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id "java-gradle-plugin" 3 | } 4 | 5 | gradlePlugin { 6 | plugins { 7 | optionalDependencies { 8 | id = "org.springframework.restdocs.toolchain" 9 | implementationClass = "org.springframework.restdocs.build.toolchain.ToolchainPlugin" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-parts.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Part|Description 3 | 4 | {{#requestParts}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/requestParts}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/antora.yml: -------------------------------------------------------------------------------- 1 | name: restdocs 2 | version: true 3 | ext: 4 | zip_contents_collector: 5 | include: 6 | - name: root 7 | classifier: aggregate-content 8 | - name: api 9 | classifier: catalog-content 10 | module: api 11 | destination: content-catalog 12 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-form-parameters.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description 3 | 4 | {{#parameters}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/parameters}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-query-parameters.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description 3 | 4 | {{#parameters}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/parameters}} 9 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-parameters.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Parameter|Description 3 | 4 | {{#parameters}} 5 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 7 | 8 | {{/parameters}} 9 | |=== -------------------------------------------------------------------------------- /config/checkstyle/checkstyle-suppressions.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /gradle/plugins/config/checkstyle/checkstyle.xml: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | 7 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/snippet-with-level.html: -------------------------------------------------------------------------------- 1 |
2 |

Curl request

3 |
4 |
5 | 
$ curl 'http://localhost:8080/' -i
6 |
7 |
8 |
-------------------------------------------------------------------------------- /gradle/plugins/optional-dependencies/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id "java-gradle-plugin" 3 | } 4 | 5 | gradlePlugin { 6 | plugins { 7 | optionalDependencies { 8 | id = "org.springframework.restdocs.optional-dependencies" 9 | implementationClass = "org.springframework.restdocs.build.optional.OptionalDependenciesPlugin" 10 | } 11 | } 12 | } -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-path-parameters.snippet: -------------------------------------------------------------------------------- 1 | .+{{path}}+ 2 | |=== 3 | |Parameter|Description 4 | 5 | {{#parameters}} 6 | |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} 7 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 8 | 9 | {{/parameters}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-fields.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description 3 | 4 | {{#fields}} 5 | |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}} 7 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 8 | 9 | {{/fields}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-response-fields.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description 3 | 4 | {{#fields}} 5 | |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}} 7 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 8 | 9 | {{/fields}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/snippet-simple.html: -------------------------------------------------------------------------------- 1 |
2 |

Curl request

3 |
4 |
5 |
6 | 
$ curl 'http://localhost:8080/' -i
7 |
8 |
9 |
10 |
-------------------------------------------------------------------------------- /spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/asciidoctor/default-request-part-fields.snippet: -------------------------------------------------------------------------------- 1 | |=== 2 | |Path|Type|Description 3 | 4 | {{#fields}} 5 | |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}} 6 | |{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}} 7 | |{{#tableCellContent}}{{description}}{{/tableCellContent}} 8 | 9 | {{/fields}} 10 | |=== -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/resources/field-payloads/multiple-fields.json: -------------------------------------------------------------------------------- 1 | { 2 | "alpha": "alpha-value", 3 | "bravo": 123, 4 | "charlie": { 5 | "one": 456, 6 | "two": "two-value" 7 | }, 8 | "delta": [ 9 | "delta-value-1", 10 | "delta-value-2" 11 | ], 12 | "echo": [{ 13 | "one": 789, 14 | "two": "two-value" 15 | },{ 16 | "one": 987, 17 | "two": "value-two" 18 | }] 19 | } -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/custom-snippet-custom-title.html: -------------------------------------------------------------------------------- 1 |
2 |

Customized title

3 |
4 |
5 |
6 | 
mycustomsnippet-äöü
7 |
8 |
9 |
10 |
-------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/custom-snippet-default-title.html: -------------------------------------------------------------------------------- 1 |
2 |

Custom snippet

3 |
4 |
5 |
6 | 
mycustomsnippet-äöü
7 |
8 |
9 |
10 |
-------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/built-in-snippet-custom-title.html: -------------------------------------------------------------------------------- 1 |
2 |

Example request

3 |
4 |
5 |
6 | 
$ curl 'http://localhost:8080/' -i
7 |
8 |
9 |
10 |
-------------------------------------------------------------------------------- /spring-restdocs-bom/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.springframework.restdocs.conventions' 3 | id "java-platform" 4 | id "maven-publish" 5 | } 6 | 7 | description = "Spring REST Docs Bill of Materials" 8 | 9 | dependencies { 10 | constraints { 11 | api(project(":spring-restdocs-asciidoctor")) 12 | api(project(":spring-restdocs-core")) 13 | api(project(":spring-restdocs-mockmvc")) 14 | api(project(":spring-restdocs-webtestclient")) 15 | } 16 | } -------------------------------------------------------------------------------- /.github/workflows/run-codeql-analysis.yml: -------------------------------------------------------------------------------- 1 | name: "Run CodeQL Analysis" 2 | on: 3 | push: 4 | pull_request: 5 | workflow_dispatch: 6 | schedule: 7 | - cron: '45 0 * * 1' 8 | permissions: read-all 9 | jobs: 10 | run-analysis: 11 | permissions: 12 | actions: read 13 | contents: read 14 | security-events: write 15 | uses: spring-io/github-actions/.github/workflows/codeql-analysis.yml@6e66995f7d29de1e4ff76e4f0def7a10163fe910 16 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/how-to/pages/index.adoc: -------------------------------------------------------------------------------- 1 | [[howto]] 2 | = How-to Guides 3 | 4 | This section provides answers to some common '`how do I do that...`' questions that arise when using Spring REST Docs. 5 | 6 | If you have a specific problem that we do not cover here, you might want to check https://stackoverflow.com/tags/spring-restdocs[stackoverflow.com] to see if someone has already provided an answer. 7 | This is also a great place to ask new questions using the `spring-restdocs` tag. 8 | -------------------------------------------------------------------------------- /.github/actions/sync-to-maven-central/artifacts.spec: -------------------------------------------------------------------------------- 1 | { 2 | "files": [ 3 | { 4 | "aql": { 5 | "items.find": { 6 | "$and": [ 7 | { 8 | "@build.name": "${buildName}", 9 | "@build.number": "${buildNumber}", 10 | "path": { 11 | "$nmatch": "org/springframework/restdocs/spring-restdocs-docs/*" 12 | } 13 | } 14 | ] 15 | } 16 | }, 17 | "target": "nexus/" 18 | } 19 | ] 20 | } 21 | -------------------------------------------------------------------------------- /settings.gradle: -------------------------------------------------------------------------------- 1 | pluginManagement { 2 | repositories { 3 | mavenCentral() 4 | gradlePluginPortal() 5 | } 6 | includeBuild "gradle/plugins" 7 | } 8 | 9 | plugins { 10 | id "io.spring.develocity.conventions" version "0.0.24" 11 | } 12 | 13 | rootProject.name = "spring-restdocs" 14 | 15 | include "spring-restdocs-asciidoctor" 16 | include "spring-restdocs-bom" 17 | include "spring-restdocs-core" 18 | include "spring-restdocs-docs" 19 | include "spring-restdocs-mockmvc" 20 | include "spring-restdocs-platform" 21 | include "spring-restdocs-webtestclient" 22 | -------------------------------------------------------------------------------- /gradle/plugins/antora/src/main/resources/antora-playbook-template.yml: -------------------------------------------------------------------------------- 1 | antora: 2 | extensions: 3 | site: 4 | title: Spring REST Docs 5 | content: 6 | sources: [] 7 | asciidoc: 8 | sourcemap: true 9 | attributes: 10 | chomp: all 11 | hide-uri-scheme: '@' 12 | javadoc-location: xref:api:java/ 13 | page-pagination: '' 14 | page-stackoverflow-url: https://stackoverflow.com/tags/spring-restdocs 15 | tabs-sync-option: '@' 16 | extensions: 17 | urls: 18 | latest_version_segment: '' 19 | runtime: 20 | log: 21 | failure_level: warn 22 | -------------------------------------------------------------------------------- /spring-restdocs-mockmvc/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.springframework.restdocs.conventions' 3 | id "java-library" 4 | id "maven-publish" 5 | id "org.springframework.restdocs.optional-dependencies" 6 | } 7 | 8 | description = "Spring REST Docs MockMvc" 9 | 10 | dependencies { 11 | api(project(":spring-restdocs-core")) 12 | api("org.springframework:spring-webmvc") 13 | api("org.springframework:spring-test") 14 | 15 | implementation("jakarta.servlet:jakarta.servlet-api") 16 | 17 | testImplementation(testFixtures(project(":spring-restdocs-core"))) 18 | } 19 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/snippet-template-format.adoc: -------------------------------------------------------------------------------- 1 | [[configuration.snippet-template-format]] 2 | = Snippet Template Format 3 | 4 | The default snippet template format is Asciidoctor. 5 | Markdown is also supported out of the box. 6 | You can change the default format by using the `RestDocumentationConfigurer` API. 7 | The following examples show how to do so: 8 | 9 | [tabs] 10 | ==== 11 | MockMvc:: 12 | + 13 | include-code::mockmvc/CustomFormat[] 14 | 15 | WebTestClient:: 16 | + 17 | include-code::webtestclient/CustomFormat[] 18 | ==== 19 | -------------------------------------------------------------------------------- /gradle/plugins/settings.gradle: -------------------------------------------------------------------------------- 1 | pluginManagement { 2 | new File(rootDir.parentFile.parentFile, "gradle.properties").withInputStream { 3 | def properties = new Properties() 4 | properties.load(it) 5 | properties.each { key, value -> 6 | if (key.endsWith("Version")) { 7 | gradle.extensions.extraProperties.set(key, value) 8 | } 9 | } 10 | } 11 | plugins { 12 | id "io.spring.javaformat" version gradle.extensions.extraProperties.get("javaFormatVersion") 13 | } 14 | } 15 | 16 | include "antora" 17 | include "conventions" 18 | include "optional-dependencies" 19 | include "toolchain" 20 | -------------------------------------------------------------------------------- /.github/actions/print-jvm-thread-dumps/action.yml: -------------------------------------------------------------------------------- 1 | name: Print JVM thread dumps 2 | description: 'Prints a thread dump for all running JVMs' 3 | runs: 4 | using: composite 5 | steps: 6 | - if: ${{ runner.os == 'Linux' }} 7 | shell: bash 8 | run: | 9 | for jvm_pid in $(jps -q -J-XX:+PerfDisableSharedMem); do 10 | jcmd $jvm_pid Thread.print 11 | done 12 | - if: ${{ runner.os == 'Windows' }} 13 | shell: powershell 14 | run: | 15 | foreach ($jvm_pid in $(jps -q -J-XX:+PerfDisableSharedMem)) { 16 | jcmd $jvm_pid Thread.print 17 | } 18 | -------------------------------------------------------------------------------- /.github/actions/await-http-resource/action.yml: -------------------------------------------------------------------------------- 1 | name: Await HTTP Resource 2 | description: 'Waits for an HTTP resource to be available (a HEAD request succeeds)' 3 | inputs: 4 | url: 5 | description: 'URL of the resource to await' 6 | required: true 7 | runs: 8 | using: composite 9 | steps: 10 | - name: Await HTTP resource 11 | shell: bash 12 | run: | 13 | url=${{ inputs.url }} 14 | echo "Waiting for $url" 15 | until curl --fail --head --silent ${{ inputs.url }} > /dev/null 16 | do 17 | echo "." 18 | sleep 60 19 | done 20 | echo "$url is available" 21 | -------------------------------------------------------------------------------- /spring-restdocs-webtestclient/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.springframework.restdocs.conventions' 3 | id "java-library" 4 | id "maven-publish" 5 | } 6 | 7 | description = "Spring REST Docs WebFlux" 8 | 9 | dependencies { 10 | api(project(":spring-restdocs-core")) 11 | api("org.springframework:spring-test") 12 | api("org.springframework:spring-webflux") 13 | 14 | compileOnly("org.hamcrest:hamcrest-core") 15 | compileOnly("com.google.code.findbugs:jsr305") 16 | 17 | testCompileOnly("org.hamcrest:hamcrest-core") 18 | 19 | testImplementation(testFixtures(project(":spring-restdocs-core"))) 20 | 21 | testRuntimeOnly("org.springframework:spring-context") 22 | } 23 | -------------------------------------------------------------------------------- /gradle/plugins/conventions/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id "java-gradle-plugin" 3 | } 4 | 5 | repositories { 6 | mavenCentral() 7 | gradlePluginPortal() 8 | } 9 | 10 | gradlePlugin { 11 | plugins { 12 | conventions { 13 | id = "org.springframework.restdocs.conventions" 14 | implementationClass = "org.springframework.restdocs.build.conventions.ConventionsPlugin" 15 | } 16 | } 17 | } 18 | 19 | dependencies { 20 | implementation(project(":toolchain")) 21 | implementation("io.spring.gradle.nullability:nullability-plugin:0.0.2") 22 | implementation("io.spring.javaformat:spring-javaformat-gradle-plugin:$javaFormatVersion") 23 | implementation("io.spring.nohttp:nohttp-gradle:0.0.11") 24 | } 25 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.springframework.restdocs.conventions' 3 | id "java-library" 4 | id "maven-publish" 5 | } 6 | 7 | description = "Spring REST Docs Asciidoctor Extension" 8 | 9 | dependencies { 10 | compileOnly("org.jspecify:jspecify") 11 | 12 | implementation("org.asciidoctor:asciidoctorj") 13 | 14 | testImplementation("org.apache.pdfbox:pdfbox") 15 | testImplementation("org.assertj:assertj-core") 16 | testImplementation("org.junit.jupiter:junit-jupiter") 17 | testImplementation("org.springframework:spring-core") 18 | 19 | testRuntimeOnly("org.asciidoctor:asciidoctorj-pdf") 20 | testRuntimeOnly("org.junit.platform:junit-platform-launcher") 21 | } 22 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/multiple-snippets.html: -------------------------------------------------------------------------------- 1 |
2 |

Curl request

3 |
4 |
5 |
6 | 
$ curl 'http://localhost:8080/' -i
7 |
8 |
9 |
10 |
11 |
12 |

HTTP request

13 |
14 |
15 |
16 | 
GET / HTTP/1.1
17 | Host: localhost:8080
18 |
19 |
20 |
21 |
-------------------------------------------------------------------------------- /.github/workflows/delete-staged-release.yml: -------------------------------------------------------------------------------- 1 | name: Delete Staged Release 2 | on: 3 | workflow_dispatch: 4 | inputs: 5 | build-version: 6 | description: 'Version of the build to delete' 7 | required: true 8 | permissions: 9 | contents: read 10 | jobs: 11 | delete-staged-release: 12 | name: Delete Staged Release 13 | runs-on: ubuntu-latest 14 | steps: 15 | - name: Set up JFrog CLI 16 | uses: jfrog/setup-jfrog-cli@9fe0f98bd45b19e6e931d457f4e98f8f84461fb5 # v4.4.1 17 | env: 18 | JF_ENV_SPRING: ${{ secrets.JF_ARTIFACTORY_SPRING }} 19 | - name: Delete Build 20 | run: jfrog rt delete --build spring-restdocs-${{ github.event.inputs.build-version }} 21 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/default-snippets.adoc: -------------------------------------------------------------------------------- 1 | [[configuration.default-snippets]] 2 | = Default Snippets 3 | 4 | Six snippets are produced by default: 5 | 6 | * `curl-request` 7 | * `http-request` 8 | * `http-response` 9 | * `httpie-request` 10 | * `request-body` 11 | * `response-body` 12 | 13 | You can change the default snippet configuration during setup by using the `RestDocumentationConfigurer` API. 14 | The following examples produce only the `curl-request` snippet by default: 15 | 16 | [tabs] 17 | ==== 18 | MockMvc:: 19 | + 20 | include-code::mockmvc/CustomDefaultSnippets[] 21 | 22 | WebTestClient:: 23 | + 24 | include-code::webtestclient/CustomDefaultSnippets[] 25 | ==== 26 | -------------------------------------------------------------------------------- /antora/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "scripts": { 3 | "antora": "node npm/antora.js" 4 | }, 5 | "dependencies": { 6 | "@antora/cli": "3.2.0-alpha.10", 7 | "@antora/site-generator": "3.2.0-alpha.10", 8 | "@antora/atlas-extension": "1.0.0-alpha.5", 9 | "@springio/antora-extensions": "1.14.7", 10 | "@springio/antora-xref-extension": "1.0.0-alpha.5", 11 | "@springio/antora-zip-contents-collector-extension": "1.0.0-alpha.10", 12 | "@asciidoctor/tabs": "1.0.0-beta.6", 13 | "@springio/asciidoctor-extensions": "1.0.0-alpha.17", 14 | "patch-package": "^8.0.0" 15 | }, 16 | "config": { 17 | "ui-bundle-url": "https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.20/ui-bundle.zip" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/snippet-in-section.html: -------------------------------------------------------------------------------- 1 |
2 |
3 |
4 |

Alpha

5 |
6 |
7 |
8 |
9 |

1. B

10 |
11 |
12 |

Bravo

13 |
14 |
15 |

1.1. Curl request

16 |
17 |
18 | 
$ curl 'http://localhost:8080/' -i
19 |
20 |
21 |
22 |
23 |
24 |
25 |

2. C

26 |
27 | 28 |
29 |
-------------------------------------------------------------------------------- /.github/actions/create-github-release/changelog-generator.yml: -------------------------------------------------------------------------------- 1 | changelog: 2 | sections: 3 | - title: ":star: New Features" 4 | labels: 5 | - "type: enhancement" 6 | - title: ":lady_beetle: Bug Fixes" 7 | labels: 8 | - "type: bug" 9 | - "type: regression" 10 | - title: ":notebook_with_decorative_cover: Documentation" 11 | labels: 12 | - "type: documentation" 13 | - title: ":hammer: Dependency Upgrades" 14 | sort: "title" 15 | labels: 16 | - "type: dependency-upgrade" 17 | issues: 18 | ports: 19 | - label: "status: forward-port" 20 | bodyExpression: 'Forward port of issue #(\d+).*' 21 | - label: "status: back-port" 22 | bodyExpression: 'Back port of issue #(\d+).*' 23 | -------------------------------------------------------------------------------- /gradle/plugins/antora/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id "java-gradle-plugin" 3 | } 4 | 5 | repositories { 6 | gradlePluginPortal() 7 | mavenCentral() 8 | } 9 | 10 | dependencies { 11 | implementation(platform("com.fasterxml.jackson:jackson-bom:2.20.1")) 12 | implementation("com.fasterxml.jackson.core:jackson-databind") 13 | implementation("com.github.node-gradle:gradle-node-plugin:7.1.0") 14 | implementation("io.spring.gradle.antora:spring-antora-plugin:0.0.1") 15 | implementation("org.yaml:snakeyaml:2.5") 16 | implementation("org.antora:gradle-antora-plugin:1.0.0") 17 | } 18 | 19 | gradlePlugin { 20 | plugins { 21 | antora { 22 | id = "org.springframework.restdocs.antora" 23 | implementationClass = "org.springframework.restdocs.build.antora.AntoraPlugin" 24 | } 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /gradle/plugins/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id "io.spring.javaformat" apply false 3 | id "base" 4 | } 5 | 6 | new File(rootDir.parentFile.parentFile, "gradle.properties").withInputStream { 7 | def properties = new Properties() 8 | properties.load(it) 9 | properties.each { key, value -> 10 | if (key.endsWith("Version")) { 11 | project.ext.set(key, value) 12 | } 13 | } 14 | } 15 | 16 | subprojects { 17 | apply plugin: "io.spring.javaformat" 18 | apply plugin: "checkstyle" 19 | 20 | repositories { 21 | mavenCentral() 22 | } 23 | 24 | checkstyle { 25 | toolVersion = "10.12.4" 26 | } 27 | 28 | dependencies { 29 | checkstyle("io.spring.javaformat:spring-javaformat-checkstyle:$javaFormatVersion") 30 | checkstyle("com.puppycrawl.tools:checkstyle:${checkstyle.toolVersion}") 31 | } 32 | } 33 | -------------------------------------------------------------------------------- /.github/workflows/build-pull-request.yml: -------------------------------------------------------------------------------- 1 | name: Build Pull Request 2 | on: pull_request 3 | permissions: 4 | contents: read 5 | jobs: 6 | build: 7 | name: Build Pull Request 8 | if: ${{ github.repository == 'spring-projects/spring-restdocs' }} 9 | runs-on: ${{ vars.UBUNTU_MEDIUM || 'ubuntu-latest' }} 10 | steps: 11 | - name: Check Out Code 12 | uses: actions/checkout@v4 13 | - name: Build 14 | id: build 15 | uses: ./.github/actions/build 16 | - name: Print JVM Thread Dumps When Cancelled 17 | if: cancelled() 18 | uses: ./.github/actions/print-jvm-thread-dumps 19 | - name: Upload Build Reports 20 | if: failure() 21 | uses: actions/upload-artifact@v4 22 | with: 23 | name: build-reports 24 | path: '**/build/reports/' 25 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/snippet-encoding.adoc: -------------------------------------------------------------------------------- 1 | [[configuration.snippet-encoding]] 2 | = Snippet Encoding 3 | 4 | The default snippet encoding is `UTF-8`. 5 | You can change the default snippet encoding by using the `RestDocumentationConfigurer` API. 6 | For example, the following examples use `ISO-8859-1`: 7 | 8 | [tabs] 9 | ==== 10 | MockMvc:: 11 | + 12 | include-code::mockmvc/CustomEncoding[] 13 | 14 | WebTestClient:: 15 | + 16 | include-code::webtestclient/CustomEncoding[] 17 | ==== 18 | 19 | TIP: When Spring REST Docs converts the content of a request or a response to a `String`, the `charset` specified in the `Content-Type` header is used if it is available. 20 | In its absence, the JVM's default `Charset` is used. 21 | You can configure the JVM's default `Charset` by using the `file.encoding` system property. 22 | -------------------------------------------------------------------------------- /gradle/plugins/toolchain/src/main/java/org/springframework/restdocs/build/toolchain/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Toolchain plugin. 19 | */ 20 | package org.springframework.restdocs.build.toolchain; 21 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/default-preprocessors.adoc: -------------------------------------------------------------------------------- 1 | [[configuration.default-preprocessors]] 2 | = Default Operation Preprocessors 3 | 4 | You can configure default request and response preprocessors during setup by using the `RestDocumentationConfigurer` API. 5 | The following examples remove the `Foo` headers from all requests and pretty print all responses: 6 | 7 | [tabs] 8 | ==== 9 | MockMvc:: 10 | + 11 | include-code::mockmvc/CustomDefaultOperationPreprocessors[] 12 | <1> Apply a request preprocessor that removes the header named `Foo`. 13 | <2> Apply a response preprocessor that pretty prints its content. 14 | 15 | WebTestClient:: 16 | + 17 | include-code::webtestclient/CustomDefaultOperationPreprocessors[] 18 | <1> Apply a request preprocessor that removes the header named `Foo`. 19 | <2> Apply a response preprocessor that pretty prints its content. 20 | ==== 21 | 22 | 23 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Core Spring REST Docs classes. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Snippet generation. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.snippet; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Support for Asciidoctor. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.asciidoctor; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/config/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Classes for configuring Spring REST Docs. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.config; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/constraints/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting a RESTful API's constraints. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.constraints; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting a RESTful API that uses hypermedia. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.hypermedia; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Template API used to render documentation snippets. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.templates; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting CLI commands required to make a request to a RESTful API. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.cli; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/cookies/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting the cookies of a RESTful API's requests and responses. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.cookies; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/generate/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Classes that drive the generation of the documentation snippets. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.generate; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting the headers of a RESTful API's requests and responses. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.headers; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting the payload of a RESTful API's requests and responses. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.payload; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/request/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting query and path parameters of requests sent to a RESTful API. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.request; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Core classes for using Spring REST Docs with Spring Test's MockMvc. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.mockmvc; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/mustache/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * JMustache-based implementation of the template API. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.templates.mustache; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/http/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Documenting the HTTP request sent to a RESTful API and the HTTP response that is 19 | * returned. 20 | */ 21 | @NullMarked 22 | package org.springframework.restdocs.http; 23 | 24 | import org.jspecify.annotations.NullMarked; 25 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Support for preprocessing an operation prior to it being documented. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.operation.preprocess; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-webtestclient/src/main/java/org/springframework/restdocs/webtestclient/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Core classes for using Spring REST Docs with Spring Framework's WebTestClient. 19 | */ 20 | @NullMarked 21 | package org.springframework.restdocs.webtestclient; 22 | 23 | import org.jspecify.annotations.NullMarked; 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/package-info.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | /** 18 | * Operation API that describes a request that was sent and the response that was received 19 | * when calling a RESTful API. 20 | */ 21 | @NullMarked 22 | package org.springframework.restdocs.operation; 23 | 24 | import org.jspecify.annotations.NullMarked; 25 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/null-safety.adoc: -------------------------------------------------------------------------------- 1 | [[documenting-your-api.null-safety]] 2 | = Null Safety 3 | 4 | Spring REST Docs is annotated with https://jspecify.dev/docs/start-here/[JSpecify ] annotations to declare the nullability of its API. 5 | To learn more about JSpecify, its https://jspecify.dev/docs/user-guide/[user guide] is recommended reading. 6 | 7 | The primary goal of declaring the nullability of the API is to prevent a `NullPointerException` from being thrown at runtime. 8 | This is achieved through build-time checks that are available with both Java and Kotlin. 9 | Performing the checks with Java requires some tooling such as https://github.com/uber/NullAway[NullAway] or an IDE that supports JSpecify annotations such as IntelliJ IDEA. 10 | The checks are available automatically with Kotlin which translates the JSpecify annotations into Kotlin's null safety. 11 | 12 | To learn more about null safety with Spring, refer to the {spring-framework-docs}/core/null-safety.html[Spring Framework reference documentation]. 13 | -------------------------------------------------------------------------------- /.github/workflows/trigger-docs-build.yml: -------------------------------------------------------------------------------- 1 | name: Trigger Docs Build 2 | on: 3 | push: 4 | branches: 'main' 5 | paths: [ 'antora/*' ] 6 | workflow_dispatch: 7 | inputs: 8 | build-refname: 9 | description: 'Git refname to build (e.g., 1.0.x)' 10 | required: false 11 | build-version: 12 | description: 'Version being build (e.g. 1.0.3-SNAPSHOT)' 13 | required: false 14 | permissions: 15 | contents: read 16 | jobs: 17 | trigger-docs-build: 18 | name: Trigger Docs Build 19 | if: github.repository_owner == 'spring-projects' 20 | runs-on: ${{ vars.UBUNTU_SMALL || 'ubuntu-latest' }} 21 | permissions: 22 | actions: write 23 | steps: 24 | - name: Check Out 25 | uses: actions/checkout@v4 26 | with: 27 | ref: docs-build 28 | - name: Trigger Workflow 29 | env: 30 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 31 | run: gh workflow run deploy-docs.yml -r docs-build -f build-refname=${{ github.event.inputs.build-refname }} -f build-version=${{ github.event.inputs.build-version }} 32 | -------------------------------------------------------------------------------- /config/checkstyle/checkstyle.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/config/NestedConfigurer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.config; 18 | 19 | /** 20 | * A configurer that is nested and, therefore, has a parent. 21 | * 22 | * @param the parent's type 23 | * @author Andy Wilkinson 24 | * @since 1.1.0 25 | */ 26 | interface NestedConfigurer { 27 | 28 | /** 29 | * Returns the configurer's parent. 30 | * @return the parent 31 | */ 32 | PARENT and(); 33 | 34 | } 35 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/OperationMessage.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | import org.springframework.http.HttpHeaders; 20 | 21 | /** 22 | * Base contract for operation requests, request parts, and responses. 23 | * 24 | * @author Andy Wilkinson 25 | */ 26 | interface OperationMessage { 27 | 28 | byte[] getContent(); 29 | 30 | String getContentAsString(); 31 | 32 | HttpHeaders getHeaders(); 33 | 34 | } 35 | -------------------------------------------------------------------------------- /.github/actions/create-github-release/action.yml: -------------------------------------------------------------------------------- 1 | name: Create GitHub Release 2 | description: 'Create the release on GitHub with a changelog' 3 | inputs: 4 | milestone: 5 | description: 'Name of the GitHub milestone for which a release will be created' 6 | required: true 7 | pre-release: 8 | description: 'Whether the release is a pre-release (a milestone or release candidate)' 9 | required: false 10 | default: 'false' 11 | token: 12 | description: 'Token to use for authentication with GitHub' 13 | required: true 14 | runs: 15 | using: composite 16 | steps: 17 | - name: Generate Changelog 18 | uses: spring-io/github-changelog-generator@185319ad7eaa75b0e8e72e4b6db19c8b2cb8c4c1 #v0.0.11 19 | with: 20 | config-file: .github/actions/create-github-release/changelog-generator.yml 21 | milestone: ${{ inputs.milestone }} 22 | token: ${{ inputs.token }} 23 | - name: Create GitHub Release 24 | shell: bash 25 | env: 26 | GITHUB_TOKEN: ${{ inputs.token }} 27 | run: gh release create ${{ format('v{0}', inputs.milestone) }} --notes-file changelog.md ${{ inputs.pre-release == 'true' && '--prerelease' || '' }} 28 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/working-with-markdown.adoc: -------------------------------------------------------------------------------- 1 | [[working-with-markdown]] 2 | = Working with Markdown 3 | 4 | This section describes the aspects of working with Markdown that are particularly relevant to Spring REST Docs. 5 | 6 | 7 | 8 | [[working-with-markdown.limitations]] 9 | == Limitations 10 | 11 | Markdown was originally designed for people writing for the web and, as such, is not as well-suited to writing documentation as Asciidoctor. 12 | Typically, these limitations are overcome by using another tool that builds on top of Markdown. 13 | 14 | Markdown has no official support for tables. 15 | Spring REST Docs' default Markdown snippet templates use https://michelf.ca/projects/php-markdown/extra/#table[Markdown Extra's table format]. 16 | 17 | 18 | 19 | [[working-with-markdown.including-snippets]] 20 | == Including Snippets 21 | 22 | Markdown has no built-in support for including one Markdown file in another. 23 | To include the generated snippets of Markdown in your documentation, you should use an additional tool that supports this functionality. 24 | One example that is particularly well-suited to documenting APIs is https://github.com/tripit/slate[Slate]. 25 | 26 | 27 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/documenting-your-api/default-snippets.adoc: -------------------------------------------------------------------------------- 1 | [[documenting-your-api.default-snippets]] 2 | = Default Snippets 3 | 4 | A number of snippets are produced automatically when you document a request and response. 5 | 6 | [cols="1,3"] 7 | |=== 8 | |Snippet | Description 9 | 10 | | `curl-request.adoc` 11 | | Contains the https://curl.haxx.se[`curl`] command that is equivalent to the `MockMvc` 12 | call that is being documented. 13 | 14 | | `httpie-request.adoc` 15 | | Contains the https://httpie.org[`HTTPie`] command that is equivalent to the `MockMvc` 16 | call that is being documented. 17 | 18 | | `http-request.adoc` 19 | | Contains the HTTP request that is equivalent to the `MockMvc` call that is being documented. 20 | 21 | | `http-response.adoc` 22 | | Contains the HTTP response that was returned. 23 | 24 | | `request-body.adoc` 25 | | Contains the body of the request that was sent. 26 | 27 | | `response-body.adoc` 28 | | Contains the body of the response that was returned. 29 | |=== 30 | 31 | You can configure which snippets are produced by default. 32 | See the xref:configuration/default-snippets.adoc#configuration.default-snippets[configuration section] for more information. 33 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/constraints/ConstraintDescriptionResolver.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.constraints; 18 | 19 | /** 20 | * Resolves a description for a {@link Constraint}. 21 | * 22 | * @author Andy Wilkinson 23 | */ 24 | public interface ConstraintDescriptionResolver { 25 | 26 | /** 27 | * Resolves the description for the given {@code constraint}. 28 | * @param constraint the constraint 29 | * @return the description 30 | */ 31 | String resolveDescription(Constraint constraint); 32 | 33 | } 34 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/how-to/pages/reusing-snippets.adoc: -------------------------------------------------------------------------------- 1 | [[how-to.reusing-snippets]] 2 | = Reusing Snippets 3 | 4 | It is common for an API that is being documented to have some features that are common across several of its resources. 5 | To avoid repetition when documenting such resources, you can reuse a `Snippet` configured with the common elements. 6 | 7 | First, create the `Snippet` that describes the common elements. 8 | The following example shows how to do so: 9 | 10 | include-code::CommonSnippets[] 11 | 12 | Second, use this snippet and add further descriptors that are resource-specific. 13 | The following examples show how to do so: 14 | 15 | [tabs] 16 | ==== 17 | MockMvc:: 18 | + 19 | include-code::mockmvc/ReusingSnippets[] 20 | <1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific to the resource that is being documented. 21 | 22 | WebTestClient:: 23 | + 24 | include-code::webtestclient/ReusingSnippets[] 25 | <1> Reuse the `pagingLinks` `Snippet`, calling `and` to add descriptors that are specific to the resource that is being documented. 26 | ==== 27 | 28 | The result of the example is that links with `rel` values of `first`, `last`, `next`, `previous`, `alpha`, and `bravo` are all documented. 29 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/Template.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.templates; 18 | 19 | import java.util.Map; 20 | 21 | /** 22 | * A compiled {@code Template} that can be rendered to a {@link String}. 23 | * 24 | * @author Andy Wilkinson 25 | * 26 | */ 27 | public interface Template { 28 | 29 | /** 30 | * Renders the template to a {@link String} using the given {@code context} for 31 | * variable/property resolution. 32 | * @param context the context to use 33 | * @return the rendered template 34 | */ 35 | String render(Map context); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentationContextProvider.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs; 18 | 19 | /** 20 | * A {@code RestDocumentationContextProvider} is used to provide access to the 21 | * {@link RestDocumentationContext}. 22 | * 23 | * @author Andy Wilkinson 24 | * @since 1.1.0 25 | */ 26 | public interface RestDocumentationContextProvider { 27 | 28 | /** 29 | * Returns a {@link RestDocumentationContext} for the operation that is about to be 30 | * performed. 31 | * @return the context for the operation 32 | */ 33 | RestDocumentationContext beforeOperation(); 34 | 35 | } 36 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/HeaderFilter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | /** 20 | * A strategy for determining whether or not a header should be excluded. 21 | * 22 | * @author Andy Wilkinson 23 | */ 24 | interface HeaderFilter { 25 | 26 | /** 27 | * Called to determine whether a header should be excluded. Return {@code true} to 28 | * exclude a header, otherwise {@code false}. 29 | * @param name the name of the header 30 | * @return {@code true} to exclude the header, otherwise {@code false} 31 | */ 32 | boolean excludeHeader(String name); 33 | 34 | } 35 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/SubsectionDescriptor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | /** 20 | * A description of a subsection, i.e. a field and all of its descendants, in a request or 21 | * response payload. 22 | * 23 | * @author Andy Wilkinson 24 | * @since 1.2.0 25 | */ 26 | public class SubsectionDescriptor extends FieldDescriptor { 27 | 28 | /** 29 | * Creates a new {@code SubsectionDescriptor} describing the subsection with the given 30 | * {@code path}. 31 | * @param path the path 32 | */ 33 | protected SubsectionDescriptor(String path) { 34 | super(path); 35 | } 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/SnippetException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | /** 20 | * A {@link RuntimeException} thrown to indicate a problem with the generation of a 21 | * documentation snippet. 22 | * 23 | * @author Andy Wilkinson 24 | */ 25 | @SuppressWarnings("serial") 26 | public class SnippetException extends RuntimeException { 27 | 28 | /** 29 | * Creates a new {@code SnippetException} described by the given {@code message}. 30 | * @param message the message that describes the problem 31 | */ 32 | public SnippetException(String message) { 33 | super(message); 34 | } 35 | 36 | } 37 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CommandFormatter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.cli; 18 | 19 | import java.util.List; 20 | 21 | /** 22 | * Formatter for CLI commands such as those included in {@link CurlRequestSnippet} and 23 | * {@link HttpieRequestSnippet}. 24 | * 25 | * @author Tomasz Kopczynski 26 | * @since 1.2.0 27 | */ 28 | public interface CommandFormatter { 29 | 30 | /** 31 | * Formats a list of {@code elements} into a single {@code String}. 32 | * @param elements the {@code String} elements to be formatted 33 | * @return a single formatted {@code String} 34 | */ 35 | String format(List elements); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/documentingyourapi/requestresponsepayloads/subsections/body/CustomSubsectionId.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.documentingyourapi.requestresponsepayloads.subsections.body; 18 | 19 | import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath; 20 | import static org.springframework.restdocs.payload.PayloadDocumentation.responseBody; 21 | 22 | class CustomSubsectionId { 23 | 24 | void customSubsectionId() { 25 | // tag::custom-subsection-id[] 26 | responseBody(beneathPath("weather.temperature").withSubsectionId("temp")); 27 | // end::custom-subsection-id[] 28 | } 29 | 30 | } 31 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/Snippet.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | import java.io.IOException; 20 | 21 | import org.springframework.restdocs.operation.Operation; 22 | 23 | /** 24 | * A {@link Snippet} is used to document aspects of a call to a RESTful API. 25 | * 26 | * @author Andy Wilkinson 27 | */ 28 | public interface Snippet { 29 | 30 | /** 31 | * Documents the call to the RESTful API described by the given {@code operation}. 32 | * @param operation the API operation 33 | * @throws IOException if a failure occurs will documenting the operation 34 | */ 35 | void document(Operation operation) throws IOException; 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/TemplateFormat.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.templates; 18 | 19 | /** 20 | * A {@link TemplateFormat} provides information about a particular template format, such 21 | * as Asciidoctor or Markdown. 22 | * 23 | * @author Andy Wilkinson 24 | * @since 1.1.0 25 | */ 26 | public interface TemplateFormat { 27 | 28 | /** 29 | * Returns the id of this template format. 30 | * @return the id 31 | */ 32 | String getId(); 33 | 34 | /** 35 | * Returns the file extension to use for files generated from templates in this 36 | * format. 37 | * @return the file extension 38 | */ 39 | String getFileExtension(); 40 | 41 | } 42 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/partials/nav-reference.adoc: -------------------------------------------------------------------------------- 1 | * xref:reference:index.adoc[] 2 | ** xref:reference:documenting-your-api/index.adoc[] 3 | *** xref:reference:documenting-your-api/null-safety.adoc[] 4 | *** xref:reference:documenting-your-api/hypermedia.adoc[] 5 | *** xref:reference:documenting-your-api/request-response-payloads.adoc[] 6 | *** xref:reference:documenting-your-api/query-parameters.adoc[] 7 | *** xref:reference:documenting-your-api/form-parameters.adoc[] 8 | *** xref:reference:documenting-your-api/path-parameters.adoc[] 9 | *** xref:reference:documenting-your-api/multipart.adoc[] 10 | *** xref:reference:documenting-your-api/http-headers.adoc[] 11 | *** xref:reference:documenting-your-api/http-cookies.adoc[] 12 | *** xref:reference:documenting-your-api/constraints.adoc[] 13 | *** xref:reference:documenting-your-api/default-snippets.adoc[] 14 | ** xref:reference:customizing-requests-and-responses.adoc[] 15 | ** xref:reference:configuration/index.adoc[] 16 | *** xref:reference:configuration/uris.adoc[] 17 | *** xref:reference:configuration/snippet-encoding.adoc[] 18 | *** xref:reference:configuration/snippet-template-format.adoc[] 19 | *** xref:reference:configuration/default-snippets.adoc[] 20 | *** xref:reference:configuration/default-preprocessors.adoc[] 21 | ** xref:reference:working-with-asciidoctor.adoc[] 22 | ** xref:reference:working-with-markdown.adoc[] 23 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/java/org/springframework/restdocs/asciidoctor/CapturingLogHandler.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.asciidoctor; 18 | 19 | import java.util.ArrayList; 20 | import java.util.List; 21 | 22 | import org.asciidoctor.log.LogHandler; 23 | import org.asciidoctor.log.LogRecord; 24 | 25 | public class CapturingLogHandler implements LogHandler { 26 | 27 | private static final List logRecords = new ArrayList(); 28 | 29 | @Override 30 | public void log(LogRecord logRecord) { 31 | logRecords.add(logRecord); 32 | } 33 | 34 | static List getLogRecords() { 35 | return logRecords; 36 | } 37 | 38 | static void clear() { 39 | logRecords.clear(); 40 | } 41 | 42 | } 43 | -------------------------------------------------------------------------------- /spring-restdocs-platform/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'java-platform' 3 | } 4 | 5 | javaPlatform { 6 | allowDependencies() 7 | } 8 | 9 | dependencies { 10 | constraints { 11 | api("com.google.code.findbugs:jsr305:3.0.2") 12 | api("com.samskivert:jmustache:1.16") 13 | api("jakarta.servlet:jakarta.servlet-api:6.1.0") 14 | api("jakarta.validation:jakarta.validation-api:3.1.1") 15 | api("org.apache.pdfbox:pdfbox:3.0.5") 16 | api("org.apache.tomcat.embed:tomcat-embed-core:11.0.11") 17 | api("org.apache.tomcat.embed:tomcat-embed-el:11.0.11") 18 | api("org.apiguardian:apiguardian-api:1.1.2") 19 | api("org.asciidoctor:asciidoctorj:3.0.0") 20 | api("org.asciidoctor:asciidoctorj-pdf:2.3.19") 21 | api("org.hamcrest:hamcrest-core:1.3") 22 | api("org.hamcrest:hamcrest-library:1.3") 23 | api("org.hibernate.validator:hibernate-validator:9.0.1.Final") 24 | api("org.jspecify:jspecify:1.0.0") 25 | api("org.javamoney:moneta:1.4.5") 26 | } 27 | api(enforcedPlatform("io.rest-assured:rest-assured-bom:5.5.6")) 28 | api(enforcedPlatform("org.apache.groovy:groovy-bom:5.0.1")) 29 | api(enforcedPlatform("org.assertj:assertj-core:3.27.4")) 30 | api(enforcedPlatform("org.mockito:mockito-bom:5.19.0")) 31 | api(enforcedPlatform("org.junit:junit-bom:6.0.1")) 32 | api(enforcedPlatform("org.springframework:spring-framework-bom:$springFrameworkVersion")) 33 | api(enforcedPlatform("tools.jackson:jackson-bom:3.0.2")) 34 | } 35 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/RequestConverter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | /** 20 | * A {@code RequestConverter} is used to convert an implementation-specific request into 21 | * an {@link OperationRequest}. 22 | * 23 | * @param the implementation-specific request type 24 | * @author Andy Wilkinson 25 | * @since 1.1.0 26 | */ 27 | public interface RequestConverter { 28 | 29 | /** 30 | * Converts the given {@code request} into an {@code OperationRequest}. 31 | * @param request the request 32 | * @return the operation request 33 | * @throws ConversionException if the conversion fails 34 | */ 35 | OperationRequest convert(R request); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/constraints/ConstraintResolver.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.constraints; 18 | 19 | import java.util.List; 20 | 21 | /** 22 | * An abstraction for resolving a class's constraints. 23 | * 24 | * @author Andy Wilkinson 25 | */ 26 | public interface ConstraintResolver { 27 | 28 | /** 29 | * Resolves and returns the constraints for the given {@code property} on the given 30 | * {@code clazz}. If there are no constraints, an empty list is returned. 31 | * @param property the property 32 | * @param clazz the class 33 | * @return the list of constraints, never {@code null} 34 | */ 35 | List resolveForProperty(String property, Class clazz); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/ResponseConverter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | /** 20 | * A {@code ResponseConverter} is used to convert an implementation-specific response into 21 | * an {@link OperationResponse}. 22 | * 23 | * @param the implementation-specific response type 24 | * @author Andy Wilkinson 25 | * @since 1.1.0 26 | */ 27 | public interface ResponseConverter { 28 | 29 | /** 30 | * Converts the given {@code response} into an {@code OperationResponse}. 31 | * @param response the response 32 | * @return the operation response 33 | * @throws ConversionException if the conversion fails 34 | */ 35 | OperationResponse convert(R response); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /gradle/plugins/conventions/src/main/java/org/springframework/restdocs/build/conventions/ConventionsPlugin.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.build.conventions; 18 | 19 | import org.gradle.api.Plugin; 20 | import org.gradle.api.Project; 21 | 22 | /** 23 | * A {@link Plugin} that applies the Spring REST Docs project's Gradle build conventions. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public class ConventionsPlugin implements Plugin { 28 | 29 | @Override 30 | public void apply(Project project) { 31 | new JavaBasePluginConventions(project).apply(); 32 | new MavenPublishPluginConventions(project).apply(); 33 | new JavaTestFixturesPluginConventions(project).apply(); 34 | new NoHttpConventions(project).apply(); 35 | } 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/OperationRequestPreprocessor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import org.springframework.restdocs.operation.OperationRequest; 20 | 21 | /** 22 | * An {@code OperationRequestPreprocessor} is used to modify an {@code OperationRequest} 23 | * prior to it being documented. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public interface OperationRequestPreprocessor { 28 | 29 | /** 30 | * Processes and potentially modifies the given {@code request} before it is 31 | * documented. 32 | * @param request the request 33 | * @return the modified request 34 | */ 35 | OperationRequest preprocess(OperationRequest request); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/PlaceholderResolverFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | import org.springframework.restdocs.RestDocumentationContext; 20 | import org.springframework.util.PropertyPlaceholderHelper.PlaceholderResolver; 21 | 22 | /** 23 | * A factory for creating {@link PlaceholderResolver} instances. 24 | * 25 | * @author Andy Wilkinson 26 | * @since 1.1.0 27 | */ 28 | public interface PlaceholderResolverFactory { 29 | 30 | /** 31 | * Creates a new {@link PlaceholderResolver} using the given {@code context}. 32 | * @param context the context 33 | * @return the placeholder resolver 34 | */ 35 | PlaceholderResolver create(RestDocumentationContext context); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/TemplateResourceResolver.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.templates; 18 | 19 | import org.springframework.core.io.Resource; 20 | 21 | /** 22 | * A {@code TemplateResourceResolver} is responsible for resolving a name for a template 23 | * into a {@link Resource} from which the template can be read. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public interface TemplateResourceResolver { 28 | 29 | /** 30 | * Resolves a {@link Resource} for the template with the given {@code name}. 31 | * @param name the name of the template 32 | * @return the {@code Resource} from which the template can be read 33 | */ 34 | Resource resolveTemplateResource(String name); 35 | 36 | } 37 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/OperationResponsePreprocessor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import org.springframework.restdocs.operation.OperationResponse; 20 | 21 | /** 22 | * An {@code OperationResponsePreprocessor} is used to modify an {@code OperationResponse} 23 | * prior to it being documented. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public interface OperationResponsePreprocessor { 28 | 29 | /** 30 | * Processes and potentially modifies the given {@code response} before it is 31 | * documented. 32 | * @param response the response 33 | * @return the modified response 34 | */ 35 | OperationResponse preprocess(OperationResponse response); 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldTypeRequiredException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | /** 20 | * A {@code FieldTypeRequiredException} is thrown when a field's type cannot be determined 21 | * automatically and, therefore, must be explicitly provided. 22 | * 23 | * @author Andy Wilkinson 24 | */ 25 | @SuppressWarnings("serial") 26 | public class FieldTypeRequiredException extends RuntimeException { 27 | 28 | /** 29 | * Creates a new {@code FieldTypeRequiredException} indicating that a type is required 30 | * for the reason described in the given {@code message}. 31 | * @param message the message 32 | */ 33 | public FieldTypeRequiredException(String message) { 34 | super(message); 35 | } 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/ROOT/pages/contributing.adoc: -------------------------------------------------------------------------------- 1 | [[contributing]] 2 | = Contributing 3 | 4 | Spring REST Docs is intended to make it easy for you to produce high-quality documentation for your RESTful services. 5 | However, we cannot achieve that goal without your contributions. 6 | 7 | 8 | 9 | [[contributing.questions]] 10 | == Questions 11 | 12 | You can ask questions about Spring REST Docs on https://stackoverflow.com[Stack Overflow] by using the `spring-restdocs` tag. 13 | Similarly, we encourage you to help your fellow Spring REST Docs users by answering questions. 14 | 15 | 16 | 17 | [[contributing.bugs]] 18 | == Bugs 19 | 20 | If you believe you have found a bug, please take a moment to search the {github}/issues?q=is%3Aissue[existing issues]. 21 | If no one else has reported the problem, please {github}/issues/new[open a new issue] that describes the problem in detail and, ideally, includes a test that reproduces it. 22 | 23 | 24 | 25 | [[contributing.enhancements]] 26 | == Enhancements 27 | 28 | If you would like an enhancement to be made to Spring REST Docs, pull requests are most welcome. 29 | The source code is on {github}[GitHub]. 30 | You may want to search the {github}/issues?q=is%3Aissue[existing issues] and {github}/pulls?q=is%3Apr[pull requests] to see if the enhancement has already been proposed. 31 | You may also want to {github}/issues/new[open a new issue] to discuss a possible enhancement before work on it begins. 32 | 33 | 34 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/ExactMatchHeaderFilter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import java.util.Arrays; 20 | import java.util.HashSet; 21 | import java.util.Set; 22 | 23 | /** 24 | * A {@link HeaderFilter} that excludes a header if its name is an exact match. 25 | * 26 | * @author Andy Wilkinson 27 | */ 28 | class ExactMatchHeaderFilter implements HeaderFilter { 29 | 30 | private final Set headersToExclude; 31 | 32 | ExactMatchHeaderFilter(String... headersToExclude) { 33 | this.headersToExclude = new HashSet<>(Arrays.asList(headersToExclude)); 34 | } 35 | 36 | @Override 37 | public boolean excludeHeader(String name) { 38 | return this.headersToExclude.contains(name); 39 | } 40 | 41 | } 42 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/config/SnippetConfiguration.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.config; 18 | 19 | import org.springframework.restdocs.templates.TemplateFormat; 20 | 21 | /** 22 | * An encapsulation of the configuration for documentation snippets. 23 | * 24 | * @author Andy Wilkinson 25 | * @since 1.1.0 26 | */ 27 | class SnippetConfiguration { 28 | 29 | private final String encoding; 30 | 31 | private final TemplateFormat format; 32 | 33 | SnippetConfiguration(String encoding, TemplateFormat templateFormat) { 34 | this.encoding = encoding; 35 | this.format = templateFormat; 36 | } 37 | 38 | String getEncoding() { 39 | return this.encoding; 40 | } 41 | 42 | TemplateFormat getTemplateFormat() { 43 | return this.format; 44 | } 45 | 46 | } 47 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/documentingyourapi/requestresponsepayloads/fields/reusingfielddescriptors/BookPayload.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.documentingyourapi.requestresponsepayloads.fields.reusingfielddescriptors; 18 | 19 | import org.springframework.restdocs.payload.FieldDescriptor; 20 | 21 | import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath; 22 | 23 | public final class BookPayload { 24 | 25 | // @fold:on 26 | private BookPayload() { 27 | 28 | } 29 | // @fold:off 30 | 31 | public static FieldDescriptor[] bookDescription() { 32 | return new FieldDescriptor[] { fieldWithPath("title").description("Title of the book"), 33 | fieldWithPath("author").description("Author of the book") }; 34 | } 35 | 36 | } 37 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/config/AbstractConfigurer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.config; 18 | 19 | import java.util.Map; 20 | 21 | import org.springframework.restdocs.RestDocumentationContext; 22 | 23 | /** 24 | * Abstract configurer that declares methods that are internal to the documentation 25 | * configuration implementation. 26 | * 27 | * @author Andy Wilkinson 28 | * @since 1.1.0 29 | */ 30 | public abstract class AbstractConfigurer { 31 | 32 | /** 33 | * Applies the configurer to the given {@code configuration}. 34 | * @param configuration the configuration to be configured 35 | * @param context the current documentation context 36 | */ 37 | public abstract void apply(Map configuration, RestDocumentationContext context); 38 | 39 | } 40 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldDoesNotExistException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | /** 20 | * A {@code FieldDoesNotExistException} is thrown when a requested field does not exist in 21 | * a payload. 22 | * 23 | * @author Andy Wilkinson 24 | */ 25 | @SuppressWarnings("serial") 26 | public class FieldDoesNotExistException extends RuntimeException { 27 | 28 | /** 29 | * Creates a new {@code FieldDoesNotExistException} that indicates that the field with 30 | * the given {@code fieldPath} does not exist. 31 | * @param fieldPath the path of the field that does not exist 32 | */ 33 | public FieldDoesNotExistException(String fieldPath) { 34 | super("The payload does not contain a field with the path '" + fieldPath + "'"); 35 | } 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/RestDocumentationContextPlaceholderResolverFactory.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | import org.springframework.restdocs.RestDocumentationContext; 20 | import org.springframework.util.PropertyPlaceholderHelper.PlaceholderResolver; 21 | 22 | /** 23 | * A {@link PlaceholderResolverFactory} that creates 24 | * {@link RestDocumentationContextPlaceholderResolver} instances. 25 | * 26 | * @author Andy Wilkinson 27 | * @since 1.1.0 28 | */ 29 | public final class RestDocumentationContextPlaceholderResolverFactory implements PlaceholderResolverFactory { 30 | 31 | @Override 32 | public PlaceholderResolver create(RestDocumentationContext context) { 33 | return new RestDocumentationContextPlaceholderResolver(context); 34 | } 35 | 36 | } 37 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/config/AbstractNestedConfigurer.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.config; 18 | 19 | /** 20 | * Base class for {@link NestedConfigurer} implementations. 21 | * 22 | * @param the type of the configurer's parent 23 | * @author Andy Wilkinson 24 | * @since 1.1.0 25 | */ 26 | public abstract class AbstractNestedConfigurer extends AbstractConfigurer implements NestedConfigurer { 27 | 28 | private final PARENT parent; 29 | 30 | /** 31 | * Creates a new {@code AbstractNestedConfigurer} with the given {@code parent}. 32 | * @param parent the parent 33 | */ 34 | protected AbstractNestedConfigurer(PARENT parent) { 35 | this.parent = parent; 36 | } 37 | 38 | @Override 39 | public final PARENT and() { 40 | return this.parent; 41 | } 42 | 43 | } 44 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/documentingyourapi/constraints/Constraints.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.documentingyourapi.constraints; 18 | 19 | import java.util.List; 20 | 21 | import jakarta.validation.constraints.NotNull; 22 | import jakarta.validation.constraints.Size; 23 | 24 | import org.springframework.restdocs.constraints.ConstraintDescriptions; 25 | 26 | class Constraints { 27 | 28 | List describeNameConstraints() { 29 | ConstraintDescriptions userConstraints = new ConstraintDescriptions(UserInput.class); // <1> 30 | return userConstraints.descriptionsForProperty("name"); // <2> 31 | } 32 | 33 | static class UserInput { 34 | 35 | @NotNull 36 | @Size(min = 1) 37 | String name; 38 | 39 | @NotNull 40 | @Size(min = 8) 41 | String password; 42 | 43 | } 44 | 45 | } 46 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/RestDocsExtensionRegistry.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.asciidoctor; 18 | 19 | import org.asciidoctor.Asciidoctor; 20 | import org.asciidoctor.jruby.extension.spi.ExtensionRegistry; 21 | 22 | /** 23 | * {@link ExtensionRegistry} for Spring REST Docs. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public final class RestDocsExtensionRegistry implements ExtensionRegistry { 28 | 29 | @Override 30 | public void register(Asciidoctor asciidoctor) { 31 | asciidoctor.javaExtensionRegistry().preprocessor(new DefaultAttributesPreprocessor()); 32 | asciidoctor.rubyExtensionRegistry() 33 | .loadClass(RestDocsExtensionRegistry.class.getResourceAsStream("/extensions/operation_block_macro.rb")) 34 | .blockMacro("operation", "OperationBlockMacro"); 35 | } 36 | 37 | } 38 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/test/resources/operations/snippet-table.html: -------------------------------------------------------------------------------- 1 |
2 |

Response fields

3 |
4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 |
PathTypeDescription

a

Object

one

a.b

Number

two

a.c

String

three

35 |
36 |
-------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadHandlingException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | /** 20 | * Thrown to indicate that a failure has occurred during payload handling. 21 | * 22 | * @author Andy Wilkinson 23 | * 24 | */ 25 | @SuppressWarnings("serial") 26 | class PayloadHandlingException extends RuntimeException { 27 | 28 | /** 29 | * Creates a new {@code PayloadHandlingException} with the given {@code message}. 30 | * @param message the message 31 | * @since 1.2.0 32 | */ 33 | PayloadHandlingException(String message) { 34 | super(message); 35 | } 36 | 37 | /** 38 | * Creates a new {@code PayloadHandlingException} with the given {@code cause}. 39 | * @param cause the cause of the failure 40 | */ 41 | PayloadHandlingException(Throwable cause) { 42 | super(cause); 43 | } 44 | 45 | } 46 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/Operation.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | import java.util.Map; 20 | 21 | /** 22 | * Describes an operation performed on a RESTful service. 23 | * 24 | * @author Andy Wilkinson 25 | */ 26 | public interface Operation { 27 | 28 | /** 29 | * Returns a {@code Map} of attributes associated with the operation. 30 | * @return the attributes 31 | */ 32 | Map getAttributes(); 33 | 34 | /** 35 | * Returns the name of the operation. 36 | * @return the name 37 | */ 38 | String getName(); 39 | 40 | /** 41 | * Returns the request that was sent. 42 | * @return the request 43 | */ 44 | OperationRequest getRequest(); 45 | 46 | /** 47 | * Returns the response that was received. 48 | * @return the response 49 | */ 50 | OperationResponse getResponse(); 51 | 52 | } 53 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/documentingyourapi/hypermedia/ignoringcommonlinks/Hypermedia.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.documentingyourapi.hypermedia.ignoringcommonlinks; 18 | 19 | import org.springframework.restdocs.hypermedia.HypermediaDocumentation; 20 | import org.springframework.restdocs.hypermedia.LinkDescriptor; 21 | import org.springframework.restdocs.hypermedia.LinksSnippet; 22 | 23 | import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel; 24 | 25 | final class Hypermedia { 26 | 27 | // @fold: on 28 | private Hypermedia() { 29 | 30 | } 31 | // @fold: off 32 | 33 | static LinksSnippet ignoreSelfAndCuries(LinkDescriptor... descriptors) { 34 | return HypermediaDocumentation.links(linkWithRel("self").ignored().optional(), linkWithRel("curies").ignored()) 35 | .and(descriptors); 36 | } 37 | 38 | } 39 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/TemplateEngine.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.templates; 18 | 19 | import java.io.IOException; 20 | 21 | import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine; 22 | 23 | /** 24 | * A {@code TemplateEngine} is used to render documentation snippets. 25 | * 26 | * @author Andy Wilkinson 27 | * @see MustacheTemplateEngine 28 | */ 29 | public interface TemplateEngine { 30 | 31 | /** 32 | * Compiles the template at the given {@code path}. Typically, a 33 | * {@link TemplateResourceResolver} will be used to resolve the path into a resource 34 | * that can be read and compiled. 35 | * @param path the path of the template 36 | * @return the compiled {@code Template} 37 | * @throws IOException if compilation fails 38 | */ 39 | Template compileTemplate(String path) throws IOException; 40 | 41 | } 42 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/gettingstarted/documentationsnippets/invokingtheservice/webtestclient/InvokeService.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.gettingstarted.documentationsnippets.invokingtheservice.webtestclient; 18 | 19 | import org.springframework.http.MediaType; 20 | import org.springframework.test.web.reactive.server.WebTestClient; 21 | 22 | import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document; 23 | 24 | class InvokeService { 25 | 26 | // @fold:on // Fields 27 | private WebTestClient webTestClient; 28 | 29 | // @fold:off 30 | 31 | void invokeService() { 32 | this.webTestClient.get() 33 | .uri("/") 34 | .accept(MediaType.APPLICATION_JSON) // <1> 35 | .exchange() 36 | .expectStatus() 37 | .isOk() // <2> 38 | .expectBody() 39 | .consumeWith(document("index")); // <3> 40 | } 41 | 42 | } 43 | -------------------------------------------------------------------------------- /gradle/plugins/conventions/src/main/java/org/springframework/restdocs/build/conventions/Conventions.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.build.conventions; 18 | 19 | import org.gradle.api.Plugin; 20 | import org.gradle.api.Project; 21 | 22 | /** 23 | * Base class for {@link Plugin} conventions. 24 | * 25 | * @param the type of plugin to which the conventions apply 26 | * @author Andy Wilkinson 27 | */ 28 | abstract class Conventions> { 29 | 30 | private final Project project; 31 | 32 | private final Class pluginType; 33 | 34 | Conventions(Project project, Class pluginType) { 35 | this.project = project; 36 | this.pluginType = pluginType; 37 | } 38 | 39 | void apply() { 40 | this.project.getPlugins().withType(this.pluginType).all(this::apply); 41 | } 42 | 43 | abstract void apply(T plugin); 44 | 45 | protected Project getProject() { 46 | return this.project; 47 | } 48 | 49 | } 50 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/FieldTypesDoNotMatchException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | /** 20 | * A {@code FieldTypesDoNotMatchException} is thrown when the documented and actual types 21 | * of a field do not match. 22 | * 23 | * @author Andy Wilkinson 24 | */ 25 | class FieldTypesDoNotMatchException extends RuntimeException { 26 | 27 | /** 28 | * Creates a new {@code FieldTypesDoNotMatchException} for the field described by the 29 | * given {@code fieldDescriptor} that has the given {@code actualType}. 30 | * @param fieldDescriptor the field 31 | * @param actualType the actual type of the field 32 | */ 33 | FieldTypesDoNotMatchException(FieldDescriptor fieldDescriptor, Object actualType) { 34 | super("The documented type of the field '" + fieldDescriptor.getPath() + "' is " + fieldDescriptor.getType() 35 | + " but the actual type is " + actualType); 36 | } 37 | 38 | } 39 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/howto/reusingsnippets/CommonSnippets.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.howto.reusingsnippets; 18 | 19 | import org.springframework.restdocs.hypermedia.LinksSnippet; 20 | 21 | import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel; 22 | import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links; 23 | 24 | public final class CommonSnippets { 25 | 26 | // @fold:on 27 | private CommonSnippets() { 28 | 29 | } 30 | // @fold:off 31 | 32 | public static final LinksSnippet pagingLinks = links( 33 | linkWithRel("first").optional().description("The first page of results"), 34 | linkWithRel("last").optional().description("The last page of results"), 35 | linkWithRel("next").optional().description("The next page of results"), 36 | linkWithRel("prev").optional().description("The previous page of results")); 37 | 38 | } 39 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/testFixtures/java/org/springframework/restdocs/testfixtures/jupiter/SnippetTemplate.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.testfixtures.jupiter; 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | /** 25 | * Customizes the template that will be used when rendering a snippet in a 26 | * {@link RenderedSnippetTest rendered snippet test}. 27 | * 28 | * @author Andy Wilkinson 29 | */ 30 | @Retention(RetentionPolicy.RUNTIME) 31 | @Target(ElementType.METHOD) 32 | public @interface SnippetTemplate { 33 | 34 | /** 35 | * The name of the snippet whose template should be customized. 36 | * @return the snippet name 37 | */ 38 | String snippet(); 39 | 40 | /** 41 | * The custom template to use when rendering the snippet. 42 | * @return the custom template 43 | */ 44 | String template(); 45 | 46 | } 47 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/test/java/org/springframework/restdocs/hypermedia/StubLinkExtractor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.hypermedia; 18 | 19 | import java.io.IOException; 20 | 21 | import org.springframework.restdocs.operation.OperationResponse; 22 | import org.springframework.util.LinkedMultiValueMap; 23 | import org.springframework.util.MultiValueMap; 24 | 25 | /** 26 | * Stub implementation of {@code LinkExtractor} for testing. 27 | * 28 | * @author Andy Wilkinson 29 | */ 30 | class StubLinkExtractor implements LinkExtractor { 31 | 32 | private MultiValueMap linksByRel = new LinkedMultiValueMap<>(); 33 | 34 | @Override 35 | public MultiValueMap extractLinks(OperationResponse response) throws IOException { 36 | return this.linksByRel; 37 | } 38 | 39 | StubLinkExtractor withLinks(Link... links) { 40 | for (Link link : links) { 41 | this.linksByRel.add(link.getRel(), link); 42 | } 43 | return this; 44 | } 45 | 46 | } 47 | -------------------------------------------------------------------------------- /spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/DefaultAttributesPreprocessor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.asciidoctor; 18 | 19 | import org.asciidoctor.ast.Document; 20 | import org.asciidoctor.extension.Preprocessor; 21 | import org.asciidoctor.extension.PreprocessorReader; 22 | import org.asciidoctor.extension.Reader; 23 | 24 | /** 25 | * {@link Preprocessor} that sets defaults for REST Docs-related {@link Document} 26 | * attributes. 27 | * 28 | * @author Andy Wilkinson 29 | */ 30 | final class DefaultAttributesPreprocessor extends Preprocessor { 31 | 32 | private final SnippetsDirectoryResolver snippetsDirectoryResolver = new SnippetsDirectoryResolver(); 33 | 34 | @Override 35 | public Reader process(Document document, PreprocessorReader reader) { 36 | document.setAttribute("snippets", this.snippetsDirectoryResolver.getSnippetsDirectory(document.getAttributes()), 37 | false); 38 | return reader; 39 | } 40 | 41 | } 42 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/reference/pages/configuration/uris.adoc: -------------------------------------------------------------------------------- 1 | [[configuration.uris]] 2 | = Documented URIs 3 | 4 | This section covers configuring documented URIs. 5 | 6 | 7 | 8 | [[configuration.uris.mockmvc]] 9 | == MockMvc URI Customization 10 | 11 | When using MockMvc, the default configuration for URIs documented by Spring REST Docs is as follows: 12 | 13 | |=== 14 | |Setting |Default 15 | 16 | |Scheme 17 | |`http` 18 | 19 | |Host 20 | |`localhost` 21 | 22 | |Port 23 | |`8080` 24 | |=== 25 | 26 | This configuration is applied by `MockMvcRestDocumentationConfigurer`. 27 | You can use its API to change one or more of the defaults to suit your needs. 28 | The following example shows how to do so: 29 | 30 | include-code::CustomUriConfiguration[] 31 | 32 | NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or port 443 for HTTPS), it is omitted from any URIs in the generated snippets. 33 | 34 | TIP: To configure a request's context path, use the `contextPath` method on `MockHttpServletRequestBuilder`. 35 | 36 | 37 | 38 | [[configuration.uris.webtestclient]] 39 | == WebTestClient URI Customization 40 | 41 | When using WebTestClient, the default base for URIs documented by Spring REST Docs is `http://localhost:8080`. 42 | You can customize this base by using the {spring-framework-api}/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-[ `baseUrl(String)` method on `WebTestClient.Builder`]. 43 | The following example shows how to do so: 44 | 45 | include-code::CustomUriConfiguration[] 46 | 47 | <1> Configure the base of documented URIs to be `https://api.example.com`. 48 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/test/java/org/springframework/restdocs/docs/gettingstarted/documentationsnippets/invokingtheservice/mockmvc/InvokeService.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.docs.gettingstarted.documentationsnippets.invokingtheservice.mockmvc; 18 | 19 | import org.springframework.http.MediaType; 20 | import org.springframework.test.web.servlet.MockMvc; 21 | 22 | import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document; 23 | import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get; 24 | import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; 25 | 26 | class InvokeService { 27 | 28 | // @fold:on // Fields 29 | 30 | private MockMvc mockMvc; 31 | 32 | // @fold:off 33 | 34 | void test() throws Exception { 35 | this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)) // <1> 36 | .andExpect(status().isOk()) // <2> 37 | .andDo(document("index")); // <3> 38 | } 39 | 40 | } 41 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/generate/RestDocumentationGenerationException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.generate; 18 | 19 | /** 20 | * An exception that can be thrown when a failure occurs during REST documentation 21 | * generation. 22 | * 23 | * @author Andy Wilkinson 24 | * @since 1.1.0 25 | */ 26 | public class RestDocumentationGenerationException extends RuntimeException { 27 | 28 | /** 29 | * Creates a new {@code RestDocumentationException} with the given {@code cause}. 30 | * @param cause the cause 31 | */ 32 | public RestDocumentationGenerationException(Throwable cause) { 33 | super(cause); 34 | } 35 | 36 | /** 37 | * Creates a new {@code RestDocumentationException} with the given {@code message} and 38 | * {@code cause}. 39 | * @param message the message 40 | * @param cause the cause 41 | */ 42 | public RestDocumentationGenerationException(String message, Throwable cause) { 43 | super(message, cause); 44 | } 45 | 46 | } 47 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/JsonFieldType.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | import java.util.Locale; 20 | 21 | import org.springframework.util.StringUtils; 22 | 23 | /** 24 | * An enumeration of the possible types for a field in a JSON request or response payload. 25 | * 26 | * @author Andy Wilkinson 27 | */ 28 | public enum JsonFieldType { 29 | 30 | /** 31 | * An array. 32 | */ 33 | ARRAY, 34 | 35 | /** 36 | * A boolean value. 37 | */ 38 | BOOLEAN, 39 | 40 | /** 41 | * An object (map). 42 | */ 43 | OBJECT, 44 | 45 | /** 46 | * A number. 47 | */ 48 | NUMBER, 49 | 50 | /** 51 | * {@code null}. 52 | */ 53 | NULL, 54 | 55 | /** 56 | * A string. 57 | */ 58 | STRING, 59 | 60 | /** 61 | * A variety of different types. 62 | */ 63 | VARIES; 64 | 65 | @Override 66 | public String toString() { 67 | return StringUtils.capitalize(this.name().toLowerCase(Locale.ENGLISH)); 68 | } 69 | 70 | } 71 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/templates/mustache/AsciidoctorTableCellContentLambda.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.templates.mustache; 18 | 19 | import java.io.IOException; 20 | import java.io.Writer; 21 | 22 | import com.samskivert.mustache.Mustache.Lambda; 23 | import com.samskivert.mustache.Template.Fragment; 24 | 25 | /** 26 | * A {@link Lambda} that escapes {@code |} characters so that the do not break the table's 27 | * formatting. 28 | * 29 | * @author Andy Wilkinson 30 | * @since 4.0.0 31 | */ 32 | public final class AsciidoctorTableCellContentLambda implements Lambda { 33 | 34 | @Override 35 | public void execute(Fragment fragment, Writer writer) throws IOException { 36 | String output = fragment.execute(); 37 | for (int i = 0; i < output.length(); i++) { 38 | char current = output.charAt(i); 39 | if (current == '|' && (i == 0 || output.charAt(i - 1) != '\\')) { 40 | writer.append('\\'); 41 | } 42 | writer.append(current); 43 | } 44 | } 45 | 46 | } 47 | -------------------------------------------------------------------------------- /gradle/plugins/toolchain/src/main/java/org/springframework/restdocs/build/toolchain/ToolchainPlugin.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.build.toolchain; 18 | 19 | import org.gradle.api.Plugin; 20 | import org.gradle.api.Project; 21 | import org.gradle.api.tasks.testing.Test; 22 | import org.gradle.jvm.toolchain.JavaLanguageVersion; 23 | import org.gradle.jvm.toolchain.JavaToolchainService; 24 | 25 | public class ToolchainPlugin implements Plugin { 26 | 27 | @Override 28 | public void apply(Project project) { 29 | String toolchainVersion = (String) project.findProperty("toolchainVersion"); 30 | if (toolchainVersion != null) { 31 | JavaToolchainService toolchainService = project.getExtensions().getByType(JavaToolchainService.class); 32 | project.getTasks() 33 | .withType(Test.class) 34 | .configureEach((test) -> test.getJavaLauncher() 35 | .set(toolchainService.launcherFor( 36 | (spec) -> spec.getLanguageVersion().set(JavaLanguageVersion.of(toolchainVersion))))); 37 | } 38 | } 39 | 40 | } 41 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinkExtractor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.hypermedia; 18 | 19 | import java.io.IOException; 20 | import java.util.List; 21 | import java.util.Map; 22 | 23 | import org.springframework.restdocs.operation.OperationResponse; 24 | 25 | /** 26 | * A {@code LinkExtractor} is used to extract {@link Link links} from a JSON response. The 27 | * expected format of the links in the response is determined by the implementation. 28 | * 29 | * @author Andy Wilkinson 30 | * 31 | */ 32 | public interface LinkExtractor { 33 | 34 | /** 35 | * Extract the links from the given {@code response}, returning a {@code Map} of links 36 | * where the keys are the link rels. 37 | * @param response the response from which the links are to be extracted 38 | * @return the extracted links, keyed by rel 39 | * @throws IOException if link extraction fails 40 | */ 41 | Map> extractLinks(OperationResponse response) throws IOException; 42 | 43 | } 44 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/RequestCookie.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | /** 20 | * A representation of a Cookie received in a request. 21 | * 22 | * @author Andy Wilkinson 23 | * @since 1.2.0 24 | */ 25 | public final class RequestCookie { 26 | 27 | private final String name; 28 | 29 | private final String value; 30 | 31 | /** 32 | * Creates a new {@code RequestCookie} with the given {@code name} and {@code value}. 33 | * @param name the name of the cookie 34 | * @param value the value of the cookie 35 | */ 36 | public RequestCookie(String name, String value) { 37 | this.name = name; 38 | this.value = value; 39 | } 40 | 41 | /** 42 | * Returns the name of the cookie. 43 | * @return the name 44 | */ 45 | public String getName() { 46 | return this.name; 47 | } 48 | 49 | /** 50 | * Returns the value of the cookie. 51 | * @return the value 52 | */ 53 | public String getValue() { 54 | return this.value; 55 | } 56 | 57 | } 58 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/ResponseCookie.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | /** 20 | * A representation of a Cookie returned in a response. 21 | * 22 | * @author Clyde Stubbs 23 | * @since 3.0 24 | */ 25 | public final class ResponseCookie { 26 | 27 | private final String name; 28 | 29 | private final String value; 30 | 31 | /** 32 | * Creates a new {@code ResponseCookie} with the given {@code name} and {@code value}. 33 | * @param name the name of the cookie 34 | * @param value the value of the cookie 35 | */ 36 | public ResponseCookie(String name, String value) { 37 | this.name = name; 38 | this.value = value; 39 | } 40 | 41 | /** 42 | * Returns the name of the cookie. 43 | * @return the name 44 | */ 45 | public String getName() { 46 | return this.name; 47 | } 48 | 49 | /** 50 | * Returns the value of the cookie. 51 | * @return the value 52 | */ 53 | public String getValue() { 54 | return this.value; 55 | } 56 | 57 | } 58 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentationContext.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs; 18 | 19 | import java.io.File; 20 | 21 | /** 22 | * {@code RestDocumentationContext} encapsulates the context in which the documentation of 23 | * a RESTful API is being performed. 24 | * 25 | * @author Andy Wilkinson 26 | */ 27 | public interface RestDocumentationContext { 28 | 29 | /** 30 | * Returns the class whose tests are currently executing. 31 | * @return the test class 32 | */ 33 | Class getTestClass(); 34 | 35 | /** 36 | * Returns the name of the test method that is currently executing. 37 | * @return the name of the test method 38 | */ 39 | String getTestMethodName(); 40 | 41 | /** 42 | * Returns the current step count. 43 | * @return the current step count 44 | */ 45 | int getStepCount(); 46 | 47 | /** 48 | * Returns the output directory to which generated snippets should be written. 49 | * @return the output directory 50 | */ 51 | File getOutputDirectory(); 52 | 53 | } 54 | -------------------------------------------------------------------------------- /.github/actions/sync-to-maven-central/action.yml: -------------------------------------------------------------------------------- 1 | name: Sync to Maven Central 2 | description: 'Syncs a release to Maven Central and waits for it to be available for use' 3 | inputs: 4 | central-token-password: 5 | description: 'Password for authentication with central.sonatype.com' 6 | required: true 7 | central-token-username: 8 | description: 'Username for authentication with central.sonatype.com' 9 | required: true 10 | jfrog-cli-config-token: 11 | description: 'Config token for the JFrog CLI' 12 | required: true 13 | spring-restdocs-version: 14 | description: 'Version of Spring REST Docs that is being synced to Central' 15 | required: true 16 | runs: 17 | using: composite 18 | steps: 19 | - name: Set Up JFrog CLI 20 | uses: jfrog/setup-jfrog-cli@9fe0f98bd45b19e6e931d457f4e98f8f84461fb5 # v4.4.1 21 | env: 22 | JF_ENV_SPRING: ${{ inputs.jfrog-cli-config-token }} 23 | - name: Download Release Artifacts 24 | shell: bash 25 | run: jf rt download --spec ${{ format('{0}/artifacts.spec', github.action_path) }} --spec-vars 'buildName=${{ format('spring-restdocs-{0}', inputs.spring-restdocs-version) }};buildNumber=${{ github.run_number }}' 26 | - name: Sync 27 | uses: spring-io/central-publish-action@0cdd90d12e6876341e82860d951e1bcddc1e51b6 # v0.2.0 28 | with: 29 | token: ${{ inputs.central-token-password }} 30 | token-name: ${{ inputs.central-token-username }} 31 | - name: Await 32 | uses: ./.github/actions/await-http-resource 33 | with: 34 | url: ${{ format('https://repo.maven.apache.org/maven2/org/springframework/restdocs/spring-restdocs-core/{0}/spring-restdocs-core-{0}.jar', inputs.spring-restdocs-version) }} 35 | -------------------------------------------------------------------------------- /spring-restdocs-docs/src/docs/antora/modules/ROOT/pages/index.adoc: -------------------------------------------------------------------------------- 1 | :navtitle: Overview 2 | = Spring REST Docs 3 | 4 | Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test or WebTestClient. 5 | 6 | The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services. 7 | 8 | Writing high-quality documentation is difficult. 9 | One way to ease that difficulty is to use tools that are well-suited to the job. 10 | To this end, Spring REST Docs uses https://asciidoctor.org[Asciidoctor] by default. 11 | Asciidoctor processes plain text and produces HTML, styled and laid out to suit your needs. 12 | If you prefer, you can also configure Spring REST Docs to use Markdown. 13 | 14 | Spring REST Docs uses snippets produced by tests written with Spring MVC's {spring-framework-docs}/testing/mockmvc.html[test framework] or Spring WebFlux's {spring-framework-docs}/testing/webtestclient.html[`WebTestClient`]. 15 | This test-driven approach helps to guarantee the accuracy of your service's documentation. 16 | If a snippet is incorrect, the test that produces it fails. 17 | 18 | Documenting a RESTful service is largely about describing its resources. 19 | Two key parts of each resource's description are the details of the HTTP requests that it consumes and the HTTP responses that it produces. 20 | Spring REST Docs lets you work with these resources and the HTTP requests and responses, shielding your documentation from the inner-details of your service's implementation. 21 | This separation helps you document your service's API rather than its implementation. 22 | It also frees you to evolve the implementation without having to rework the documentation. 23 | 24 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/AbstractJsonLinkExtractor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.hypermedia; 18 | 19 | import java.io.IOException; 20 | import java.util.List; 21 | import java.util.Map; 22 | 23 | import tools.jackson.databind.ObjectMapper; 24 | 25 | import org.springframework.restdocs.operation.OperationResponse; 26 | 27 | /** 28 | * Abstract base class for a {@link LinkExtractor} that extracts links from JSON. 29 | * 30 | * @author Andy Wilkinson 31 | */ 32 | abstract class AbstractJsonLinkExtractor implements LinkExtractor { 33 | 34 | private final ObjectMapper objectMapper = new ObjectMapper(); 35 | 36 | @Override 37 | @SuppressWarnings("unchecked") 38 | public Map> extractLinks(OperationResponse response) throws IOException { 39 | Map jsonContent = this.objectMapper.readValue(response.getContent(), Map.class); 40 | return extractLinks(jsonContent); 41 | } 42 | 43 | protected abstract Map> extractLinks(Map json); 44 | 45 | } 46 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/PatternMatchHeaderFilter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import java.util.HashSet; 20 | import java.util.Set; 21 | import java.util.regex.Pattern; 22 | 23 | /** 24 | * A {@link HeaderFilter} that excludes a header if its name matches a {@link Pattern}. 25 | * 26 | * @author Andy Wilkinson 27 | * @author Roland Huss 28 | */ 29 | class PatternMatchHeaderFilter implements HeaderFilter { 30 | 31 | private Set exclusionPatterns; 32 | 33 | PatternMatchHeaderFilter(String... exclusionPatterns) { 34 | this.exclusionPatterns = new HashSet<>(); 35 | for (String exclusionPattern : exclusionPatterns) { 36 | this.exclusionPatterns.add(Pattern.compile(exclusionPattern)); 37 | } 38 | } 39 | 40 | @Override 41 | public boolean excludeHeader(String name) { 42 | for (Pattern pattern : this.exclusionPatterns) { 43 | if (pattern.matcher(name).matches()) { 44 | return true; 45 | } 46 | } 47 | return false; 48 | } 49 | 50 | } 51 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/ModelCreationException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | /** 20 | * An exception that can be thrown by a {@link TemplatedSnippet} to indicate that a 21 | * failure has occurred during model creation. 22 | * 23 | * @author Andy Wilkinson 24 | * @see TemplatedSnippet#createModel(org.springframework.restdocs.operation.Operation) 25 | */ 26 | @SuppressWarnings("serial") 27 | public class ModelCreationException extends RuntimeException { 28 | 29 | /** 30 | * Creates a new {@code ModelCreationException} with the given {@code cause}. 31 | * @param cause the cause 32 | */ 33 | public ModelCreationException(Throwable cause) { 34 | super(cause); 35 | } 36 | 37 | /** 38 | * Creates a new {@code ModelCreationException} with the given {@code message} and 39 | * {@code cause}. 40 | * @param message the message 41 | * @param cause the cause 42 | */ 43 | public ModelCreationException(String message, Throwable cause) { 44 | super(message, cause); 45 | } 46 | 47 | } 48 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/OperationPreprocessor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import org.springframework.restdocs.operation.Operation; 20 | import org.springframework.restdocs.operation.OperationRequest; 21 | import org.springframework.restdocs.operation.OperationResponse; 22 | 23 | /** 24 | * An {@code OperationPreprocessor} processes the {@link OperationRequest} and 25 | * {@link OperationResponse} of an {@link Operation} prior to it being documented. 26 | * 27 | * @author Andy Wilkinson 28 | */ 29 | public interface OperationPreprocessor { 30 | 31 | /** 32 | * Processes the given {@code request}. 33 | * @param request the request to process 34 | * @return the processed request 35 | */ 36 | OperationRequest preprocess(OperationRequest request); 37 | 38 | /** 39 | * Processes the given {@code response}. 40 | * @param response the response to process 41 | * @return the processed response 42 | */ 43 | OperationResponse preprocess(OperationResponse response); 44 | 45 | } 46 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/ConversionException.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation; 18 | 19 | /** 20 | * An exception that can be thrown by {@link RequestConverter} and 21 | * {@link ResponseConverter} implementations to indicate that a failure has occurred 22 | * during conversion. 23 | * 24 | * @author Andy Wilkinson 25 | * @since 1.1.0 26 | * @see RequestConverter#convert(Object) 27 | * @see ResponseConverter#convert(Object) 28 | */ 29 | public class ConversionException extends RuntimeException { 30 | 31 | /** 32 | * Creates a new {@code ConversionException} with the given {@code cause}. 33 | * @param cause the cause 34 | */ 35 | public ConversionException(Throwable cause) { 36 | super(cause); 37 | } 38 | 39 | /** 40 | * Creates a new {@code ConversionException} with the given {@code message} and 41 | * {@code cause}. 42 | * @param message the message 43 | * @param cause the cause 44 | */ 45 | public ConversionException(String message, Throwable cause) { 46 | super(message, cause); 47 | } 48 | 49 | } 50 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/constraints/Constraint.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.constraints; 18 | 19 | import java.util.Map; 20 | 21 | /** 22 | * A constraint. 23 | * 24 | * @author Andy Wilkinson 25 | */ 26 | public class Constraint { 27 | 28 | private final String name; 29 | 30 | private final Map configuration; 31 | 32 | /** 33 | * Creates a new {@code Constraint} with the given {@code name} and 34 | * {@code configuration}. 35 | * @param name the name 36 | * @param configuration the configuration 37 | */ 38 | public Constraint(String name, Map configuration) { 39 | this.name = name; 40 | this.configuration = configuration; 41 | } 42 | 43 | /** 44 | * Returns the name of the constraint. 45 | * @return the name 46 | */ 47 | public String getName() { 48 | return this.name; 49 | } 50 | 51 | /** 52 | * Returns the configuration of the constraint. 53 | * @return the configuration 54 | */ 55 | public Map getConfiguration() { 56 | return this.configuration; 57 | } 58 | 59 | } 60 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/IgnorableDescriptor.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | /** 20 | * Base class for descriptors for items that can be ignored. 21 | * 22 | * @param the type of the descriptor 23 | * @author Andy Wilkinson 24 | */ 25 | public abstract class IgnorableDescriptor> extends AbstractDescriptor { 26 | 27 | private boolean ignored = false; 28 | 29 | /** 30 | * Marks the described item as being ignored. Ignored items are not included in the 31 | * generated documentation. 32 | * @return the descriptor 33 | */ 34 | @SuppressWarnings("unchecked") 35 | public final T ignored() { 36 | this.ignored = true; 37 | return (T) this; 38 | } 39 | 40 | /** 41 | * Returns whether or not the item being described should be ignored and, therefore, 42 | * should not be included in the documentation. 43 | * @return {@code true} if the item should be ignored, otherwise {@code false}. 44 | */ 45 | public final boolean isIgnored() { 46 | return this.ignored; 47 | } 48 | 49 | } 50 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/testFixtures/java/org/springframework/restdocs/testfixtures/jupiter/SnippetTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.testfixtures.jupiter; 18 | 19 | import java.lang.annotation.ElementType; 20 | import java.lang.annotation.Retention; 21 | import java.lang.annotation.RetentionPolicy; 22 | import java.lang.annotation.Target; 23 | 24 | import org.junit.jupiter.api.Test; 25 | import org.junit.jupiter.api.extension.ExtendWith; 26 | 27 | import org.springframework.restdocs.snippet.Snippet; 28 | 29 | /** 30 | * Signals that a method is a test of a {@link Snippet}. Typically used to test scenarios 31 | * where a failure occurs before the snippet is rendered. To test snippet rendering, use 32 | * {@link RenderedSnippetTest}. 33 | *

34 | * A snippet test method can inject the following types: 35 | *

    36 | *
  • {@link OperationBuilder}
    • 37 | *
38 | * 39 | * @author Andy Wilkinson 40 | */ 41 | @Test 42 | @Target(ElementType.METHOD) 43 | @Retention(RetentionPolicy.RUNTIME) 44 | @ExtendWith(SnippetTestExtension.class) 45 | public @interface SnippetTest { 46 | 47 | } 48 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/ContentModifier.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.operation.preprocess; 18 | 19 | import org.jspecify.annotations.Nullable; 20 | 21 | import org.springframework.http.MediaType; 22 | import org.springframework.restdocs.operation.OperationRequest; 23 | import org.springframework.restdocs.operation.OperationResponse; 24 | 25 | /** 26 | * A {@code ContentModifier} modifies the content of an {@link OperationRequest} or 27 | * {@link OperationResponse} during the preprocessing that is performed prior to 28 | * documentation generation. 29 | * 30 | * @author Andy Wilkinson 31 | * @see ContentModifyingOperationPreprocessor 32 | */ 33 | public interface ContentModifier { 34 | 35 | /** 36 | * Returns modified content based on the given {@code originalContent}. 37 | * @param originalContent the original content 38 | * @param contentType the type of the original content, may be {@code null} 39 | * @return the modified content 40 | */ 41 | byte[] modifyContent(byte[] originalContent, @Nullable MediaType contentType); 42 | 43 | } 44 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/snippet/WriterResolver.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.snippet; 18 | 19 | import java.io.IOException; 20 | import java.io.Writer; 21 | 22 | import org.springframework.restdocs.RestDocumentationContext; 23 | 24 | /** 25 | * A {@code WriterResolver} is used to access the {@link Writer} that should be used to 26 | * write a snippet for an operation that is being documented. 27 | * 28 | * @author Andy Wilkinson 29 | */ 30 | public interface WriterResolver { 31 | 32 | /** 33 | * Returns a writer that can be used to write the snippet with the given name for the 34 | * operation with the given name. 35 | * @param operationName the name of the operation that is being documented 36 | * @param snippetName the name of the snippet 37 | * @param restDocumentationContext the current documentation context 38 | * @return the writer 39 | * @throws IOException if a writer cannot be resolved 40 | */ 41 | Writer resolve(String operationName, String snippetName, RestDocumentationContext restDocumentationContext) 42 | throws IOException; 43 | 44 | } 45 | -------------------------------------------------------------------------------- /spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/JsonFieldTypes.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2014-present the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package org.springframework.restdocs.payload; 18 | 19 | import java.util.Collections; 20 | import java.util.HashSet; 21 | import java.util.Iterator; 22 | import java.util.Set; 23 | 24 | /** 25 | * {@link JsonFieldType Types} for a field discovered in a JSON payload. 26 | * 27 | * @author Andy Wilkinson 28 | */ 29 | class JsonFieldTypes implements Iterable { 30 | 31 | private final Set fieldTypes; 32 | 33 | JsonFieldTypes(JsonFieldType fieldType) { 34 | this(Collections.singleton(fieldType)); 35 | } 36 | 37 | JsonFieldTypes(Set fieldTypes) { 38 | this.fieldTypes = fieldTypes; 39 | } 40 | 41 | JsonFieldType coalesce(boolean optional) { 42 | Set types = new HashSet<>(this.fieldTypes); 43 | if (optional && types.size() > 1) { 44 | types.remove(JsonFieldType.NULL); 45 | } 46 | if (types.size() == 1) { 47 | return types.iterator().next(); 48 | } 49 | return JsonFieldType.VARIES; 50 | } 51 | 52 | @Override 53 | public Iterator iterator() { 54 | return this.fieldTypes.iterator(); 55 | } 56 | 57 | } 58 | -------------------------------------------------------------------------------- /spring-restdocs-core/build.gradle: -------------------------------------------------------------------------------- 1 | plugins { 2 | id 'org.springframework.restdocs.conventions' 3 | id "java-library" 4 | id "java-test-fixtures" 5 | id "maven-publish" 6 | id "org.springframework.restdocs.optional-dependencies" 7 | } 8 | 9 | description = "Spring REST Docs Core" 10 | 11 | dependencies { 12 | compileOnly("org.apiguardian:apiguardian-api") 13 | 14 | implementation("tools.jackson.core:jackson-databind") 15 | implementation("org.springframework:spring-web") 16 | implementation("com.samskivert:jmustache") 17 | 18 | optional(platform(project(":spring-restdocs-platform"))) 19 | optional("jakarta.validation:jakarta.validation-api") 20 | optional("org.hibernate.validator:hibernate-validator") 21 | optional("org.junit.jupiter:junit-jupiter-api") 22 | 23 | testFixturesApi(platform(project(":spring-restdocs-platform"))) 24 | testFixturesApi("org.assertj:assertj-core") 25 | testFixturesApi("org.junit.jupiter:junit-jupiter") 26 | testFixturesApi("org.mockito:mockito-core") 27 | 28 | testFixturesCompileOnly("org.apiguardian:apiguardian-api") 29 | 30 | testFixturesImplementation("com.samskivert:jmustache") 31 | testFixturesImplementation("org.hamcrest:hamcrest-library") 32 | testFixturesImplementation("org.mockito:mockito-core") 33 | testFixturesImplementation("org.springframework:spring-core") 34 | testFixturesImplementation("org.springframework:spring-web") 35 | 36 | testFixturesRuntimeOnly("org.junit.platform:junit-platform-launcher") 37 | 38 | testCompileOnly("org.apiguardian:apiguardian-api") 39 | 40 | testImplementation("org.assertj:assertj-core") 41 | testImplementation("org.javamoney:moneta") 42 | testImplementation("org.mockito:mockito-core") 43 | testImplementation("org.springframework:spring-test") 44 | 45 | testRuntimeOnly("org.apache.tomcat.embed:tomcat-embed-el") 46 | testRuntimeOnly("org.junit.platform:junit-platform-engine") 47 | } 48 | --------------------------------------------------------------------------------