[REQ] General improvement of AsciiDoc generation #11396
Labels
Comments
|
EDIT: deleted grumble about passthrough of notation, which is related to #9324 But... 👍 yes please, this general improvement would be very useful! |
osfameron
added a commit
to osfameron/docs-site
that referenced
this issue
Jun 14, 2022
Block extension to filter text like:
[markdown]
--
Filter some text with [Markdown](https://commonmark.org/help/) syntax.
--
This is not implemented with a full Markdown parser.
See asciidoctor/kramdown-asciidoc#7
with a link to the "naive series of regexes" used as starting point.
(And note that we use Open structural context
https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/#summary-of-structural-containers
with `--` delimiters, and headings don’t work inside these.)
This feature is intended for handling OpenAPI specs, which can contain Markdown,
however openapi-generator has poor Asciidoc handling
OpenAPITools/openapi-generator#11396
so instead we add the block delimiters in the template, and let the block filter handle it.
osfameron
added a commit
to osfameron/docs-site
that referenced
this issue
Jul 1, 2022
Block extension to filter text like:
[markdown]
--
Filter some text with [Markdown](https://commonmark.org/help/) syntax.
--
This is not implemented with a full Markdown parser.
See asciidoctor/kramdown-asciidoc#7
with a link to the "naive series of regexes" used as starting point.
(And note that we use Open structural context
https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/#summary-of-structural-containers
with `--` delimiters, and headings don’t work inside these.)
This feature is intended for handling OpenAPI specs, which can contain Markdown,
however openapi-generator has poor Asciidoc handling
OpenAPITools/openapi-generator#11396
so instead we add the block delimiters in the template, and let the block filter handle it.
Create a block with potentially multiple lines (sub-paragraphs)
* Add extensions doc page
|
It would be nice to expose to Mustache temlplates:
|
We are actually considering to leave Open API Tools and create our own jinja2 templates instead due to Open API Tools using Mustache which is logic less. |
|
Our work with our own jinja2 template for OpenAPI Spec to AsciiDoc using jinja2 has started. We are hoping to release it as open source. |
|
@lfvjimisola any updates on your open source project? |
Yes, see: https://github.com/luftfartsverket/openapi-to-asciidoc |
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
The generated AsciiDoc output is not complete if you compare it to standard swagger.ui (e.g Petstore). Missing things are e.g.
appDescriptionadditional property #7851and other such as
Describe the solution you'd like
Update mustaché templates to output more of the information in OpenAPI spec file when generating AsciiDoc.
Describe alternatives you've considered
None other than completely manual writing.
The text was updated successfully, but these errors were encountered: