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 repositlries
• 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.