diff --git a/.gitignore b/.gitignore index a19f098892..0b191ce310 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,7 @@ target/ vf.gf.* out/ _site +node_modules +package-lock.json +package.json +node diff --git a/README.adoc b/README.adoc index 1c7019a5a8..0e88821207 100644 --- a/README.adoc +++ b/README.adoc @@ -2,7 +2,7 @@ The goal of the project is to provide a flexible and configurable mechanism for writing simple services that can be exposed over HTTP. -The first exporter implemented is a JPA Repository exporter. This takes your JPA repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations. +This takes your Spring Data repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations. == Features @@ -15,7 +15,7 @@ The first exporter implemented is a JPA Repository exporter. This takes your JPA * https://docs.spring.io/spring-data/rest/docs/current/reference/html/#metadata[Exposes metadata] about the model discovered as ALPS and JSON Schema. * Allows to define client specific representations through https://docs.spring.io/spring-data/rest/docs/current/reference/html/#projections-excerpts[projections]. * Ships the latest release of https://docs.spring.io/spring-data/rest/docs/current/reference/html/#tools.hal-explorer[HAL Explorer] to easily explore HAL and HAL-FORMS based HTTP responses. -* Currently supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire. +* Supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire. * Allows https://docs.spring.io/spring-data/rest/docs/current/reference/html/#customizing-sdr[advanced customizations] of the default resources exposed. == Code of Conduct diff --git a/spring-data-rest-distribution/pom.xml b/spring-data-rest-distribution/pom.xml index 853ea428ad..874e7b0616 100644 --- a/spring-data-rest-distribution/pom.xml +++ b/spring-data-rest-distribution/pom.xml @@ -19,18 +19,38 @@ ${basedir}/.. - SDREST + ${project.basedir}/../src/main/antora/antora-playbook.yml + + + ${project.basedir}/../src/main/antora/resources/antora-resources + true + + org.apache.maven.plugins maven-assembly-plugin + + + org.apache.maven.plugins + maven-resources-plugin + + + + resources + + + + + + - org.asciidoctor - asciidoctor-maven-plugin + io.spring.maven.antora + antora-maven-plugin diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml new file mode 100644 index 0000000000..4fa8c60534 --- /dev/null +++ b/src/main/antora/antora-playbook.yml @@ -0,0 +1,37 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'data-rest' +site: + title: Spring Data REST + url: https://docs.spring.io/spring-data-rest/reference/ +content: + sources: + - url: ./../../.. + branches: HEAD + start_path: src/main/antora + worktrees: true +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip + snapshot: true diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml new file mode 100644 index 0000000000..c7f815e229 --- /dev/null +++ b/src/main/antora/antora.yml @@ -0,0 +1,12 @@ +name: data-rest +version: true +title: Spring Data REST +nav: + - modules/ROOT/nav.adoc +ext: + collector: + - run: + command: ./mvnw validate process-resources -pl :spring-data-rest-distribution -am -Pantora-process-resources + local: true + scan: + dir: spring-data-rest-distribution/target/classes/ diff --git a/src/main/antora/modules/ROOT/examples/mongodb b/src/main/antora/modules/ROOT/examples/mongodb new file mode 120000 index 0000000000..d9e836422f --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/mongodb @@ -0,0 +1 @@ +../../../../../../spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb \ No newline at end of file diff --git a/src/main/antora/modules/ROOT/examples/security b/src/main/antora/modules/ROOT/examples/security new file mode 120000 index 0000000000..a7aec32098 --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/security @@ -0,0 +1 @@ +../../../../../../spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security \ No newline at end of file diff --git a/src/main/antora/modules/ROOT/examples/support b/src/main/antora/modules/ROOT/examples/support new file mode 120000 index 0000000000..41699764a0 --- /dev/null +++ b/src/main/antora/modules/ROOT/examples/support @@ -0,0 +1 @@ +../../../../../../spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support \ No newline at end of file diff --git a/src/main/antora/modules/ROOT/images/hal-explorer-1.png b/src/main/antora/modules/ROOT/images/hal-explorer-1.png new file mode 100644 index 0000000000..4fd634d543 Binary files /dev/null and b/src/main/antora/modules/ROOT/images/hal-explorer-1.png differ diff --git a/src/main/antora/modules/ROOT/images/hal-explorer-2.png b/src/main/antora/modules/ROOT/images/hal-explorer-2.png new file mode 100644 index 0000000000..2f3fcf756f Binary files /dev/null and b/src/main/antora/modules/ROOT/images/hal-explorer-2.png differ diff --git a/src/main/antora/modules/ROOT/images/hal-explorer-3.png b/src/main/antora/modules/ROOT/images/hal-explorer-3.png new file mode 100644 index 0000000000..d3753f2891 Binary files /dev/null and b/src/main/antora/modules/ROOT/images/hal-explorer-3.png differ diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc new file mode 100644 index 0000000000..8d89de62c0 --- /dev/null +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -0,0 +1,30 @@ +* xref:index.adoc[] + +* xref:intro.adoc[] +** xref:introduction/upgrade.adoc[] +** xref:introduction/getting-started.adoc[] +** xref:introduction/example-api-usage-with-curl.adoc[] +** xref:introduction/spring-data-rest-examples.adoc[] + +* xref:repository-resources.adoc[] +** xref:paging-and-sorting.adoc[] +** xref:projections-excerpts.adoc[] + +* xref:representations.adoc[Representations] +* xref:etags-and-other-conditionals.adoc[Conditional Operations] +* xref:validation.adoc[] +* xref:events.adoc[] +* xref:integration.adoc[] +* xref:metadata.adoc[] +* xref:security.adoc[] +* xref:tools.adoc[] + +* xref:customizing-sdr.adoc[] +** xref:customizing/configuring-the-rest-url-path.adoc[] +** xref:customizing/adding-sdr-to-spring-mvc-app.adoc[] +** xref:customizing/overriding-sdr-response-handlers.adoc[] +** xref:customizing/customizing-json-output.adoc[] +** xref:customizing/custom-jackson-deserialization.adoc[] +** xref:customizing/configuring-cors.adoc[] + +* https://github.com/spring-projects/spring-data-commons/wiki[Wiki] diff --git a/src/main/asciidoc/customizing-sdr.adoc b/src/main/antora/modules/ROOT/pages/customizing-sdr.adoc similarity index 90% rename from src/main/asciidoc/customizing-sdr.adoc rename to src/main/antora/modules/ROOT/pages/customizing-sdr.adoc index afa372b3ef..810710ef77 100644 --- a/src/main/asciidoc/customizing-sdr.adoc +++ b/src/main/antora/modules/ROOT/pages/customizing-sdr.adoc @@ -68,7 +68,7 @@ Notice how `getResourceIdentifier(…)` returns the username to be used by the U [[customizing-sdr.repository-exposure]] == Customizing repository exposure -By default, all public Spring Data repositories are used to expose HTTP resources as described in <>. +By default, all public Spring Data repositories are used to expose HTTP resources as described in xref:repository-resources.adoc[Repository resources]. Package protected repository interfaces are excluded from this list, as you express its functionality is only visible to the package internally. This can be customized by explicitly setting a `RepositoryDetectionStrategy` (usually through the enum `RepositoryDetectionStrategies`) on `RepositoryRestConfiguration`. The following values can be configured: @@ -86,12 +86,12 @@ If you need custom rules to apply, simply implement `RepositoryDetectionStrategy [[customizing-sdr.http-methods.default-exposure]] === Customizing default exposure -By default, Spring Data REST exposes HTTP resources and methods as described in <> based on which CRUD methods the repository exposes. +By default, Spring Data REST exposes HTTP resources and methods as described in xref:repository-resources.adoc[Repository resources] based on which CRUD methods the repository exposes. The repositories don't need to extend `CrudRepository` but can also selectively declare methods described in aforementioned section and the resource exposure will follow. E.g. if a repository does not expose a `delete(…)` method, an HTTP `DELETE` will not be supported for item resources. If you need to declare a method for internal use but don't want it to trigger the HTTP method exposure, the repository method can be annotated with `@RestResource(exported = false)`. -Which methods to annotate like that to remove support for which HTTP method is described in <>. +Which methods to annotate like that to remove support for which HTTP method is described in xref:repository-resources.adoc[Repository resources]. Sometimes managing the exposure on the method level is not fine-grained enough. E.g. the `save(…)` method is used to back `POST` on collection resources, as well as `PUT` and `PATCH` on item resources. @@ -110,9 +110,3 @@ config.withItemExposure((metadata, httpMethods) -> httpMethods.disable(HttpMetho <2> Disables the support for HTTP `PATCH` on all item resources. -include::configuring-the-rest-url-path.adoc[leveloffset=+1] -include::adding-sdr-to-spring-mvc-app.adoc[leveloffset=+1] -include::overriding-sdr-response-handlers.adoc[leveloffset=+1] -include::customizing-json-output.adoc[leveloffset=+1] -include::custom-jackson-deserialization.adoc[leveloffset=+1] -include::configuring-cors.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/adding-sdr-to-spring-mvc-app.adoc b/src/main/antora/modules/ROOT/pages/customizing/adding-sdr-to-spring-mvc-app.adoc similarity index 100% rename from src/main/asciidoc/adding-sdr-to-spring-mvc-app.adoc rename to src/main/antora/modules/ROOT/pages/customizing/adding-sdr-to-spring-mvc-app.adoc diff --git a/src/main/asciidoc/configuring-cors.adoc b/src/main/antora/modules/ROOT/pages/customizing/configuring-cors.adoc similarity index 100% rename from src/main/asciidoc/configuring-cors.adoc rename to src/main/antora/modules/ROOT/pages/customizing/configuring-cors.adoc diff --git a/src/main/asciidoc/configuring-the-rest-url-path.adoc b/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc similarity index 100% rename from src/main/asciidoc/configuring-the-rest-url-path.adoc rename to src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc diff --git a/src/main/asciidoc/custom-jackson-deserialization.adoc b/src/main/antora/modules/ROOT/pages/customizing/custom-jackson-deserialization.adoc similarity index 100% rename from src/main/asciidoc/custom-jackson-deserialization.adoc rename to src/main/antora/modules/ROOT/pages/customizing/custom-jackson-deserialization.adoc diff --git a/src/main/asciidoc/customizing-json-output.adoc b/src/main/antora/modules/ROOT/pages/customizing/customizing-json-output.adoc similarity index 100% rename from src/main/asciidoc/customizing-json-output.adoc rename to src/main/antora/modules/ROOT/pages/customizing/customizing-json-output.adoc diff --git a/src/main/asciidoc/overriding-sdr-response-handlers.adoc b/src/main/antora/modules/ROOT/pages/customizing/overriding-sdr-response-handlers.adoc similarity index 100% rename from src/main/asciidoc/overriding-sdr-response-handlers.adoc rename to src/main/antora/modules/ROOT/pages/customizing/overriding-sdr-response-handlers.adoc diff --git a/src/main/asciidoc/etags-and-other-conditionals.adoc b/src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc similarity index 94% rename from src/main/asciidoc/etags-and-other-conditionals.adoc rename to src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc index 8d66b8436f..9f92076d4a 100644 --- a/src/main/asciidoc/etags-and-other-conditionals.adoc +++ b/src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc @@ -1,6 +1,5 @@ [[conditional]] = Conditional Operations with Headers -:spring-data-rest-root: ../../.. This section shows how Spring Data REST uses standard HTTP headers to enhance performance, conditionalize operations, and contribute to a more sophisticated frontend. @@ -15,7 +14,7 @@ Consider the following example: ==== [source,java,indent=0] ---- -include::{spring-data-rest-root}/spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support/ETagUnitTests.java[tag=versioned-sample] +include::example$support/ETagUnitTests.java[tag=versioned-sample] ---- <1> The `@Version` annotation (the JPA one in case you're using Spring Data JPA, the Spring Data `org.springframework.data.annotation.Version` one for all other modules) flags this field as a version marker. @@ -56,7 +55,7 @@ The https://tools.ietf.org/html/rfc7232#section-3.3[`If-Modified-Since` header] ==== [source,java] ---- -include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb/Receipt.java[tag=code] +include::example$mongodb/Receipt.java[tag=code] ---- <1> Spring Data Commons's `@LastModifiedDate` annotation allows capturing this information in multiple formats (JodaTime's `DateTime`, legacy Java `Date` and `Calendar`, JDK8 date/time types, and `long`/`Long`). diff --git a/src/main/asciidoc/events.adoc b/src/main/antora/modules/ROOT/pages/events.adoc similarity index 100% rename from src/main/asciidoc/events.adoc rename to src/main/antora/modules/ROOT/pages/events.adoc diff --git a/src/main/antora/modules/ROOT/pages/index.adoc b/src/main/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000000..7f6200b7d8 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,27 @@ +[[spring-data-rest-reference-documentation]] += Spring Data REST +:feature-scroll: true + +_Spring Data REST exports Spring Data repositories as REST resources through WebMVC. +It eases development of applications with a consistent programming model backed by Spring Data modules sources._ + +[horizontal] +xref:intro.adoc[Introduction] :: Introduction to Spring Data REST and Examples +xref:repository-resources.adoc[Repository Resources] :: Exporting Repositories as REST Resources +xref:representations.adoc[Representations] :: Domain Object Representations (Object Mapping) +xref:etags-and-other-conditionals.adoc[Conditionals] :: Conditional Operations with ETag and other Headers +xref:validation.adoc[Validation] :: Validator Integration +xref:events.adoc[Events] :: Listening to REST Events +xref:integration.adoc[Integration] :: Integration with Spring Data REST components +xref:metadata.adoc[Metadata] :: ALPS and JSON Schema +xref:security.adoc[Security] :: Spring Security Integration +xref:tools.adoc[Tools] :: HAL Explorer +xref:customizing-sdr.adoc[Customizing] :: Tutorials and Recipes to customize Spring Data REST +https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, +Upgrade Notes, Supported Versions, additional cross-version information. + +Jon Brisbin, Oliver Drotbohm, Greg Turnquist, Jay Bryant + +(C) 2008-2023 VMware, Inc. + +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. diff --git a/src/main/asciidoc/integration.adoc b/src/main/antora/modules/ROOT/pages/integration.adoc similarity index 98% rename from src/main/asciidoc/integration.adoc rename to src/main/antora/modules/ROOT/pages/integration.adoc index a9f63557a7..ac04cb33cf 100644 --- a/src/main/asciidoc/integration.adoc +++ b/src/main/antora/modules/ROOT/pages/integration.adoc @@ -1,6 +1,5 @@ [[integration]] = Integration -:spring-data-rest-root: ../../../.. This section details various ways to integrate with Spring Data REST components, whether from a Spring application that is using Spring Data REST or from other means. diff --git a/src/main/asciidoc/intro.adoc b/src/main/antora/modules/ROOT/pages/intro.adoc similarity index 96% rename from src/main/asciidoc/intro.adoc rename to src/main/antora/modules/ROOT/pages/intro.adoc index b41cee7f5a..8e5c61f4f0 100644 --- a/src/main/asciidoc/intro.adoc +++ b/src/main/antora/modules/ROOT/pages/intro.adoc @@ -1,5 +1,6 @@ [[intro-chapter]] = Introduction +:page-section-summary-toc: 1 REST web services have become the number one means for application integration on the web. In its core, REST defines that a system that consists of resources with which clients interact. These resources are implemented in a hypermedia-driven way. link:{springDocsUrl}/web.html#spring-web[Spring MVC] and link:{springDocsUrl}/web-reactive.html#spring-webflux[Spring WebFlux] each offer a solid foundation to build theses kinds of services. However, implementing even the simplest tenet of REST web services for a multi-domain object system can be quite tedious and result in a lot of boilerplate code. diff --git a/src/main/asciidoc/example-api-usage-with-curl.adoc b/src/main/antora/modules/ROOT/pages/introduction/example-api-usage-with-curl.adoc similarity index 88% rename from src/main/asciidoc/example-api-usage-with-curl.adoc rename to src/main/antora/modules/ROOT/pages/introduction/example-api-usage-with-curl.adoc index 74585f57f4..69f02aa2bc 100644 --- a/src/main/asciidoc/example-api-usage-with-curl.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/example-api-usage-with-curl.adoc @@ -1,6 +1,8 @@ [[example-api-usage-with-curl]] [appendix] +[[using-curl-to-talk-to-spring-data-rest]] = Using cURL to talk to Spring Data REST +:page-section-summary-toc: 1 This appendix contains a list of guides that demonstrate interacting with a Spring Data REST service over cURL: diff --git a/src/main/asciidoc/getting-started.adoc b/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc similarity index 94% rename from src/main/asciidoc/getting-started.adoc rename to src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc index 07d9b827c2..2875cca410 100644 --- a/src/main/asciidoc/getting-started.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc @@ -89,9 +89,9 @@ Make sure you also configure Spring Data repositories for the store you use. For This section covers the basic settings that you can manipulate when you configure a Spring Data REST application, including: -* <> -* <> -* <> +* xref:introduction/getting-started.adoc#getting-started.setting-repository-detection-strategy[Setting the Repository Detection Strategy] +* xref:introduction/getting-started.adoc#getting-started.changing-base-uri[Changing the Base URI] +* xref:introduction/getting-started.adoc#getting-started.changing-other-properties[Changing Other Spring Data REST Properties] [[getting-started.setting-repository-detection-strategy]] === Setting the Repository Detection Strategy @@ -209,4 +209,4 @@ You can run your application as either a Spring Boot app (with the links shown e NOTE: In general, Spring Data REST does not add functionality to a given data store. This means that, by definition, it should work with any Spring Data project that supports the repository programming model. The data stores listed above are the ones for which we have written integration tests to verify that Spring Data REST works with them. -From this point, you can <> with various options. +From this point, you can xref:customizing-sdr.adoc[customize Spring Data REST] with various options. diff --git a/src/main/asciidoc/spring-data-rest-examples.adoc b/src/main/antora/modules/ROOT/pages/introduction/spring-data-rest-examples.adoc similarity index 93% rename from src/main/asciidoc/spring-data-rest-examples.adoc rename to src/main/antora/modules/ROOT/pages/introduction/spring-data-rest-examples.adoc index 81c441a095..ed500792f1 100644 --- a/src/main/asciidoc/spring-data-rest-examples.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/spring-data-rest-examples.adoc @@ -1,5 +1,6 @@ [[spring-data-examples]] [appendix] +[[spring-data-rest-example-projects]] = Spring Data REST example projects This appendix contains a list of Spring Data REST sample applications. The exact version of each example is not guaranteed to match the version of this reference manual. @@ -14,7 +15,7 @@ https://github.com/spring-projects/spring-data-examples/tree/master/rest/multi-s [[spring-data-examples.projections]] == Projections -https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore <>. +https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore xref:projections-excerpts.adoc[projections]. [[spring-data-examples.spring-security]] == Spring Data REST with Spring Security diff --git a/src/main/antora/modules/ROOT/pages/introduction/upgrade.adoc b/src/main/antora/modules/ROOT/pages/introduction/upgrade.adoc new file mode 100644 index 0000000000..c9f659a7c5 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/introduction/upgrade.adoc @@ -0,0 +1,8 @@ +[[new-features]] +[[upgrading]] += Upgrading Spring Data + +Instructions for how to upgrade from earlier versions of Spring Data are provided on the project https://github.com/spring-projects/spring-data-commons/wiki[wiki]. +Follow the links in the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[release notes section] to find the version that you want to upgrade to. + +Upgrading instructions are always the first item in the release notes. If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped. diff --git a/src/main/asciidoc/metadata.adoc b/src/main/antora/modules/ROOT/pages/metadata.adoc similarity index 94% rename from src/main/asciidoc/metadata.adoc rename to src/main/antora/modules/ROOT/pages/metadata.adoc index 75c702c6dc..111a0c696a 100644 --- a/src/main/asciidoc/metadata.adoc +++ b/src/main/antora/modules/ROOT/pages/metadata.adoc @@ -178,7 +178,7 @@ shown in the preceding table. === ALPS with Projections If you define any projections, they are also listed in the ALPS metadata. Assuming we also defined `inlineAddress` and `noAddresses`, they -would appear inside the relevant operations. (See "`<>`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows +would appear inside the relevant operations. (See "`xref:projections-excerpts.adoc#projections-excerpts.projections[Projections]`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows the alternate version of the `get-persons` subsection: ==== @@ -319,7 +319,7 @@ https://json-schema.org/[JSON Schema] is another form of metadata supported by S * Clear, human- and machine-readable documentation * Complete structural validation, useful for automated testing and validating client-submitted data -As shown in the <>, you can reach this data by navigating from the root URI to the `profile` link. +As shown in the xref:metadata.adoc#metadata.alps[previous section], you can reach this data by navigating from the root URI to the `profile` link. ==== [source,javascript] @@ -417,7 +417,7 @@ You can also find a `profile` link in the collection of `_links` when you examin <2> It has a *profile* link to the same URI for metadata. ==== -Again, the `profile` link serves <> by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation. +Again, the `profile` link serves xref:metadata.adoc#metadata.alps[ALPS] by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation. //= JSON Patch diff --git a/src/main/asciidoc/paging-and-sorting.adoc b/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc similarity index 100% rename from src/main/asciidoc/paging-and-sorting.adoc rename to src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc diff --git a/src/main/asciidoc/projections-excerpts.adoc b/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc similarity index 94% rename from src/main/asciidoc/projections-excerpts.adoc rename to src/main/antora/modules/ROOT/pages/projections-excerpts.adoc index 64ee102efa..b687416d90 100644 --- a/src/main/asciidoc/projections-excerpts.adoc +++ b/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc @@ -142,7 +142,7 @@ NOTE: The value supplied to the `projection` query parameter is the same as that You can have multiple projections. -NOTE: See <> to see an example project. We encourage you to experiment with it. +NOTE: See xref:introduction/spring-data-rest-examples.adoc#spring-data-examples.projections[Projections] to see an example project. We encourage you to experiment with it. Spring Data REST finds projection definitions as follows: @@ -154,7 +154,7 @@ In either case, the projection interface must have the `@Projection` annotation. [[projections-excerpts.finding-projections]] === Finding Existing Projections -Spring Data REST exposes <> documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example: +Spring Data REST exposes xref:metadata.adoc#metadata.alps[Application-Level Profile Semantics (ALPS)] documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example: ==== [source,javascript] diff --git a/src/main/asciidoc/repository-resources.adoc b/src/main/antora/modules/ROOT/pages/repository-resources.adoc similarity index 84% rename from src/main/asciidoc/repository-resources.adoc rename to src/main/antora/modules/ROOT/pages/repository-resources.adoc index f11663e876..142744330b 100644 --- a/src/main/asciidoc/repository-resources.adoc +++ b/src/main/antora/modules/ROOT/pages/repository-resources.adoc @@ -13,9 +13,9 @@ public interface OrderRepository extends CrudRepository { } ---- ==== -For this repository, Spring Data REST exposes a collection resource at `/orders`. The path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed. It also exposes an item resource for each of the items managed by the repository under the URI template `/orders/{id}`. +For this repository, Spring Data REST exposes a collection resource at `/orders`. The path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed. It also exposes an item resource for each of the items managed by the repository under the URI template `/orders/\{id}`. -By default the HTTP methods to interact with these resources map to the according methods of `CrudRepository`. Read more on that in the sections on <> and <>. +By default, the HTTP methods to interact with these resources map to the according methods of `CrudRepository`. Read more on that in the sections on xref:repository-resources.adoc#repository-resources.collection-resource[collection resources] and xref:repository-resources.adoc#repository-resources.item-resource[item resources]. [[repository-resources.methods]] === Repository methods exposure @@ -26,7 +26,7 @@ If you extend `CrudRepository` you usually expose all methods required to expose Each of the resources listed below will define which of the methods need to be present so that a particular HTTP method can be exposed for each of the resources. That means, that repositories that are not exposing those methods -- either by not declaring them at all or explicitly using `@RestResource(exported = false)` -- won't expose those HTTP methods on those resources. -For details on how to tweak the default method exposure or dedicated HTTP methods individually see <>. +For details on how to tweak the default method exposure or dedicated HTTP methods individually see xref:customizing-sdr.adoc#customizing-sdr.http-methods[Customizing supported HTTP methods]. [[repository-resources.default-status-codes]] === Default Status Codes @@ -39,7 +39,7 @@ For the resources exposed, we use a set of default status codes: If the configuration value is set to include responses for `PUT`, `200 OK` is returned for updates, and `201 Created` is returned for resource created through `PUT`. If the configuration values (`RepositoryRestConfiguration.returnBodyOnUpdate(…)` and `RepositoryRestConfiguration.returnBodyCreate(…)`) are explicitly set to `null` -- which they are by default --, the presence of the HTTP Accept header is used to determine the response code. -Read more on this in the detailed description of <> and <>. +Read more on this in the detailed description of xref:repository-resources.adoc#repository-resources.collection-resource.supported-methods.post[collection] and xref:repository-resources.adoc#repository-resources.item-resource.supported-methods.put[item resources]. [[repository-resources.resource-discoverability]] === Resource Discoverability @@ -72,7 +72,7 @@ curl -v http://localhost:8080/ The property of the result document is an object that consists of keys representing the relation type, with nested link objects as specified in HAL. -NOTE: For more details about the `profile` link, see <>. +NOTE: For more details about the `profile` link, see xref:metadata.adoc#metadata.alps[Application-Level Profile Semantics (ALPS)]. [[repository-resources.collection-resource]] == The Collection Resource @@ -90,6 +90,7 @@ Collections resources support both `GET` and `POST`. All other HTTP methods caus Returns all entities the repository servers through its `findAll(…)` method. If the repository is a paging repository we include the pagination links if necessary and additional page metadata. + ===== Methods used for invocation The following methods are used if present (descending order): @@ -98,8 +99,9 @@ The following methods are used if present (descending order): - `findAll(Sort)` - `findAll()` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. +[[parameters]] ===== Parameters If the repository has pagination capabilities, the resource takes the following parameters: @@ -114,6 +116,7 @@ The `GET` method has only one custom status code: * `405 Method Not Allowed`: If the `findAll(…)` methods were not exported (through `@RestResource(exported = false)`) or are not present in the repository. +[[supported-media-types]] ===== Supported Media Types The `GET` method supports the following media types: @@ -121,11 +124,12 @@ The `GET` method supports the following media types: * `application/hal+json` * `application/json` +[[related-resources]] ===== Related Resources The `GET` method supports a single link for discovering related resources: -* `search`: A <> is exposed if the backing repository exposes query methods. +* `search`: A xref:repository-resources.adoc#repository-resources.search-resource[search resource] is exposed if the backing repository exposes query methods. [[repository-resources.collection-resource.supported-methods.head]] ==== `HEAD` @@ -140,7 +144,7 @@ The following methods are used if present (descending order): - `findAll(Sort)` - `findAll()` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. [[repository-resources.collection-resource.supported-methods.post]] ==== `POST` @@ -157,7 +161,7 @@ The following methods are used if present (descending order): - `save(…)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. ===== Custom Status Codes @@ -180,20 +184,21 @@ Spring Data REST exposes a resource for individual collection items as sub-resou [[repository-resources.item-resource.supported-methods]] === Supported HTTP Methods -Item resources generally support `GET`, `PUT`, `PATCH`, and `DELETE`, unless explicit configuration prevents that (see "`<>`" for details). +Item resources generally support `GET`, `PUT`, `PATCH`, and `DELETE`, unless explicit configuration prevents that (see "`xref:repository-resources.adoc#repository-resources.association-resource[The Association Resource]`" for details). [[repository-resources.item-resource.supported-methods.get]] ==== GET The `GET` method returns a single entity. + ===== Methods used for invocation The following methods are used if present (descending order): - `findById(…)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. ===== Custom Status Codes @@ -210,20 +215,21 @@ The `GET` method supports the following media types: ===== Related Resources -For every association of the domain type, we expose links named after the association property. You can customize this behavior by using `@RestResource` on the property. The related resources are of the <> type. +For every association of the domain type, we expose links named after the association property. You can customize this behavior by using `@RestResource` on the property. The related resources are of the xref:repository-resources.adoc#repository-resources.association-resource[association resource] type. [[repository-resources.item-resource.supported-methods.head]] ==== `HEAD` The `HEAD` method returns whether the item resource is available. It has no status codes, media types, or related resources. + ===== Methods used for invocation The following methods are used if present (descending order): - `findById(…)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. [[repository-resources.item-resource.supported-methods.put]] ==== `PUT` @@ -234,13 +240,14 @@ If the request header is present, a response body and a status code of `200 OK` If no header is present, the response body is empty and a successful request returns a status of `204 No Content`. This behavior can be overridden by configuring `RepositoryRestConfiguration.setReturnBodyOnUpdate(…)` accordingly. + ===== Methods used for invocation The following methods are used if present (descending order): - `save(…)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. ===== Custom Status Codes @@ -260,13 +267,14 @@ The `PUT` method supports the following media types: The `PATCH` method is similar to the `PUT` method but partially updates the resources state. + ===== Methods used for invocation The following methods are used if present (descending order): - `save(…)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. ===== Custom Status Codes @@ -292,6 +300,7 @@ If the request header is present, a response body and a status code of `200 OK` If no header is present, the response body is empty and a successful request returns a status of `204 No Content`. This behavior can be overridden by configuring `RepositoryRestConfiguration.setReturnBodyOnDelete(…)` accordingly. + ===== Methods used for invocation The following methods are used if present (descending order): @@ -300,7 +309,7 @@ The following methods are used if present (descending order): - `delete(ID)` - `delete(Iterable)` -For more information on the default exposure of methods, see <>. +For more information on the default exposure of methods, see xref:repository-resources.adoc#repository-resources.methods[Repository methods exposure]. ===== Custom Status Codes @@ -368,6 +377,7 @@ The `POST` method supports only one media type: The `DELETE` method unbinds the association. +[[custom-status-codes]] ===== Custom Status Codes The `POST` method has only one custom status code: @@ -398,7 +408,7 @@ The `GET` method supports the following media types: ===== Related Resources -For every query method declared in the repository, we expose a <>. If the resource supports pagination, the URI pointing to it is a URI template containing the pagination parameters. +For every query method declared in the repository, we expose a xref:repository-resources.adoc#repository-resources.query-method-resource[query method resource]. If the resource supports pagination, the URI pointing to it is a URI template containing the pagination parameters. [[repository-resources.search-resource.supported-methods.head]] ==== `HEAD` diff --git a/src/main/asciidoc/representations.adoc b/src/main/antora/modules/ROOT/pages/representations.adoc similarity index 100% rename from src/main/asciidoc/representations.adoc rename to src/main/antora/modules/ROOT/pages/representations.adoc diff --git a/src/main/asciidoc/security.adoc b/src/main/antora/modules/ROOT/pages/security.adoc similarity index 85% rename from src/main/asciidoc/security.adoc rename to src/main/antora/modules/ROOT/pages/security.adoc index ef9c3852f3..21b052e829 100644 --- a/src/main/asciidoc/security.adoc +++ b/src/main/antora/modules/ROOT/pages/security.adoc @@ -1,6 +1,5 @@ [[security]] = Security -:spring-data-rest-root: ../../.. :spring-security-docs: https://docs.spring.io/spring-security/reference Spring Data REST works quite well with Spring Security. This section shows examples of how to secure your Spring Data REST services with method-level security. @@ -15,7 +14,7 @@ The following example from Spring Data REST's test suite shows Spring Security's [source,java] ---- -include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/PreAuthorizedOrderRepository.java[tag=code] +include::example$security/PreAuthorizedOrderRepository.java[tag=code] ---- <1> This Spring Security annotation secures the entire repository. The {spring-security-docs}/servlet/authorization/expression-based.html[Spring Security SpEL expression] indicates that the principal must have `ROLE_USER` in its collection of roles. @@ -38,7 +37,7 @@ The following example shows Spring Security's older `@Secured` annotation, which ==== [source,java] ---- -include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/SecuredPersonRepository.java[tag=code] +include::example$security/SecuredPersonRepository.java[tag=code] ---- <1> This results in the same security check as the previous example but has less flexibility. It allows only roles as the means to restrict access. @@ -56,7 +55,7 @@ To configure method-level security, here is a brief snippet from Spring Data RES ==== [source,java] ---- -include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security/SecurityConfiguration.java[tag=code] +include::example$security/SecurityConfiguration.java[tag=code] ... } ---- diff --git a/src/main/asciidoc/tools.adoc b/src/main/antora/modules/ROOT/pages/tools.adoc similarity index 94% rename from src/main/asciidoc/tools.adoc rename to src/main/antora/modules/ROOT/pages/tools.adoc index 0f638a4c41..fe3fff186a 100644 --- a/src/main/asciidoc/tools.adoc +++ b/src/main/antora/modules/ROOT/pages/tools.adoc @@ -1,6 +1,5 @@ [[tools]] = Tools -:spring-data-rest-root: ../../../.. [[tools.hal-explorer]] == The HAL Explorer @@ -48,7 +47,7 @@ The HAL Explorer understands *URI Templates*. Whenever a link contains a URI tem image::hal-explorer-3.png[] -If you click *Go!* without entering anything, the variables are essentially ignored. For situations like <> or <>, this can be useful. +If you click *Go!* without entering anything, the variables are essentially ignored. For situations like xref:projections-excerpts.adoc[Projections and Excerpts] or xref:paging-and-sorting.adoc[Paging and Sorting], this can be useful. When you click on a *NON-GET* button with a `+` or a `>` sign on it, a modal dialog appears. It shows the HTTP method belonging to the clicked button. You can fill the body and submit the new JSON document. diff --git a/src/main/asciidoc/validation.adoc b/src/main/antora/modules/ROOT/pages/validation.adoc similarity index 100% rename from src/main/asciidoc/validation.adoc rename to src/main/antora/modules/ROOT/pages/validation.adoc diff --git a/src/main/antora/resources/antora-resources/antora.yml b/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 0000000000..e629aebf2b --- /dev/null +++ b/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,19 @@ +version: ${antora-component.version} +prerelease: ${antora-component.prerelease} + +asciidoc: + attributes: + version: ${project.version} + springversionshort: ${spring.short} + springversion: ${spring} + attribute-missing: 'warn' + commons: ${springdata.commons.docs} + include-xml-namespaces: false + spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference + spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/ + springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort} + springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api + spring-framework-docs: '{springdocsurl}' + spring-framework-javadoc: '{springjavadocurl}' + springhateoasversion: ${spring-hateoas} + releasetrainversion: ${releasetrain} diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc deleted file mode 100644 index a0cab7ae5a..0000000000 --- a/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[[spring-data-rest-reference]] -= Spring Data REST Reference Guide -Jon Brisbin, Oliver Drotbohm, Greg Turnquist, Jay Bryant -:revnumber: {version} -:revdate: {localdate} -ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]] -:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc - -(C) 2012-2022 Original authors - -NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. - -include::preface.adoc[] -include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] -include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1] - -[[reference]] -= Reference Documentation - -include::intro.adoc[leveloffset=+1] -include::getting-started.adoc[leveloffset=+1] -include::repository-resources.adoc[leveloffset=+1] -include::paging-and-sorting.adoc[leveloffset=+1] -include::representations.adoc[leveloffset=+1] -include::projections-excerpts.adoc[leveloffset=+1] -include::etags-and-other-conditionals.adoc[leveloffset=+1] -include::validation.adoc[leveloffset=+1] -include::events.adoc[leveloffset=+1] -include::integration.adoc[leveloffset=+1] -include::metadata.adoc[leveloffset=+1] -include::security.adoc[leveloffset=+1] -include::tools.adoc[leveloffset=+1] -include::customizing-sdr.adoc[leveloffset=+1] - -[[appendix]] -= Appendix - -:numbered!: -include::example-api-usage-with-curl.adoc[leveloffset=+1] -include::spring-data-rest-examples.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc deleted file mode 100644 index e844b54c59..0000000000 --- a/src/main/asciidoc/preface.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[preface]] -= Preface - -[[Project]] -[preface] -== Project Metadata - -* Version control: https://github.com/spring-projects/spring-data-rest -* Bugtracker: https://github.com/spring-projects/spring-data-rest/issues -* Project page: https://spring.io/projects/spring-data-rest -* Release repository: https://repo1.maven.org/maven2/ -* Milestone repository: https://repo.spring.io/milestone/ -* Snapshot repository: https://repo.spring.io/snapshot