diff --git a/docs/src/docs/asciidoc/documenting-your-api.adoc b/docs/src/docs/asciidoc/documenting-your-api.adoc index f798b34a..9242fcbc 100644 --- a/docs/src/docs/asciidoc/documenting-your-api.adoc +++ b/docs/src/docs/asciidoc/documenting-your-api.adoc @@ -84,6 +84,22 @@ If your API represents its links in a format other than Atom or HAL, you can pro own implementation of the `LinkExtractor` interface to extract the links from the response. + + +[[documenting-your-api-hypermedia-ignoring-common-links]] +==== Ignoring common links + +Rather than documenting links that are common to every response, such as `_self` and +`curies` when using HAL, you may want to document them once in an overview section and +then ignore them in the rest of your API's documentation. To do so, you can build on the +<> to add link +descriptors to a snippet that's preconfigured to ignore certain links. For example: + +[source,java,indent=0] +---- +include::{examples-dir}/com/example/Hypermedia.java[tags=ignore-links] +---- + [[documenting-your-api-request-response-payloads]] === Request and response payloads diff --git a/docs/src/test/java/com/example/Hypermedia.java b/docs/src/test/java/com/example/Hypermedia.java new file mode 100644 index 00000000..10f16868 --- /dev/null +++ b/docs/src/test/java/com/example/Hypermedia.java @@ -0,0 +1,34 @@ +/* + * Copyright 2014-2016 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.example; + +import org.springframework.restdocs.hypermedia.HypermediaDocumentation; +import org.springframework.restdocs.hypermedia.LinkDescriptor; +import org.springframework.restdocs.hypermedia.LinksSnippet; + +import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel; + +public class Hypermedia { + + // tag::ignore-links[] + public static LinksSnippet links(LinkDescriptor... descriptors) { + return HypermediaDocumentation.links(linkWithRel("_self").ignored().optional(), + linkWithRel("curies").ignored()).and(descriptors); + } + // end::ignore-links[] + +}