Tag regions of Asciidoctor snippets to allow their contents to be selectively included

[davidgoate]

When documenting some endpoint which returns protobuf format, I'd find it useful to be able to document the response headers without the body. Currently this is what I get:

HTTP/1.1 200 OK
Content-Type: application/x-protobuf
X-Protobuf-Schema: proto1.proto
X-Protobuf-Message: com.org.project.Proto1
Content-Length: 226


��
�GBP���"�33.31*�
�GBP���2
�GBP����

Sadly, the automatically generated snippets are:

• curl-request.adoc
• http-request.adoc
• http-response.adoc
• httpie-request.adoc
• request-body.adoc
• response-body.adoc

Note that there is not one that includes just the response headers without the body. I can work around this in a slightly hacky way by doing my include like this include::filename.txt[lines=0..5] however, obviously this is a little brittle if new headers should appear and I don't update this to include them (they will be chopped off).

I'd like to request as a feature either:

1. Adding a new snippet with just the response headers and no body.
2. Ascii doctors seems to support a concept of tagged regions as seen here: https://asciidoctor.org/docs/user-manual/#by-tagged-regions which would allow the http-response.adoc to potentially include tags for the headers and body which could then improve how I can include just the headers.

[wilkinsona]

Using tags in the snippets is an interesting idea. Thanks.

In the meantime, I typically use a pre-processor to change the body of the response to something that's better-suited to being documented. For example:

this.mvc.perform(get("/")).andDo(document("example",
	preprocessResponse(new ContentModifyingOperationPreprocessor(
		(context, mediaType) -> "<<binary data>>".getBytes()))));

[davidgoate]

@wilkinsona thanks for the advice, sadly the tags and line solution isn't actually as useful as I first considered. Because the snippet contains the formatting

[source,http,options="nowrap"]
----

and

----

the solution is a little ugly. I'd have to manually include the leading lines and final line or do the include and manually type the formatting around it.

[wilkinsona]

You can include multiple tags in a single include, so I think your idea still warrants some investigation. I'm not sure what the tag for the "surrounding stuff" should be called, but this doesn't seem too awkward:

include::http-response.rb[tags=stuff;headers]

That said, this will only benefit those who are using Asciidoctor. Perhaps separate snippets for the HTTP request and response that just contain the headers are in order. That would provide a nice symmetry with the existing snippets that just contain the HTTP request body and HTTP response body.