search

Swagger2Markup / swagger2markup

A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.
Apache License 2.0
2.5k stars 382 forks source link

Some sections should be broken into separate lines #25

Closed who closed 9 years ago

who commented 9 years ago

swagger2markup generates the following URI scheme information:

=== URI scheme
Host: example.com
BasePath: /api
Schemes: HTTPS

However, because these lines are not hard returns, the actual interpretation of these lines is:

URI scheme Host: example.comBasePath: /apiSchemes: HTTPS

This makes for some unsightly output when using asciidoctor to convert the adoc to HTML.

How do we change the output which swagger2markup chooses, in order to customize the newlines for this section, and other sections like it?

I'd like the section to render adocs which use the + symbol, signifying a hard break:

=== URI scheme
Host: example.com +
BasePath: /api +
Schemes: HTTPS +
RobWin commented 9 years ago

You must add the Asciidoctor attribute hardbreaks in your Gradle or Maven Plugin. See https://swagger2markup.readme.io/docs/demo in Gradle. 

asciidoctor {
    dependsOn convertSwagger2markup
    sources {
        include 'index.adoc'
    }
    backends = ['html5', 'pdf']
    attributes = [
            doctype: 'book',
            toc: 'left',
            toclevels: '2',
            numbered: '',
            sectlinks: '',
            sectanchors: '',
            hardbreaks: '',
            generated: asciiDocOutputDir
    ]
}

As an alternative you can add the attribute :hardbreaks: in your index.adoc.

who commented 9 years ago

Good to know, thanks @RobWin ! I'm using swagger2markup-cli in conjunction with the npm module asciidoctorjs-cli, and I can pass the options for hardbreaks.

RobWin commented 9 years ago

You are welcome. A sample/demo/blog of your tech stack would be nice. I could add it to the documentation.