Asciidoctor lets us reference source code and embed it in documents.
It would be a nice thing to avoid the painful copy paste that needs to happen at every specification release cycle.
A few potential drawbacks:
the sources for the spec and the api are in diffferent repositories
the sources references need to target a specific git commit reference (like a release tag). Otherwise building an old version of the spec might reference newer version of the code.
code in the spec has been adjusted to not go to the next line - or rather beyond the end of the sheet - in the past. But I think asciidoctor has better and nicer support with its wrapping approach. So this might not be a problem.
That'd be nice indeed. There could be a step in the build which fetches the right API version and copies it into some working dir from where it can be extracted.
The concerns above are addressed by fetching a specific API version from the local Maven repo.