Add ability to insert page breaks in certain positions

[cascer1]

I'd like to be able to set a configuration item to start certain sections on a new page.

For example: It should be possible to say that each new operation (path/method combination) has to start on a new page.

I believe this makes the document look much cleaner.

[RobWin]

Hi,

you mean you want to add something like Asciidoctors <<<?

[cascer1]

Exactly!

I'm writing a program to convert RAML specs to PDF and found that the output looked much cleaner after starting each new method on a new page.

[RobWin]

How do you convert Raml to AsciiDoc? Do you use Swagger2Markup?

[cascer1]

I'm writing my own tool to convert raml to asciidoc. The repo is private but will be made public within a month probably

[RobWin]

Very nice.
Is the design similar to Swagger2Markup or different?

[cascer1]

It also generates asciidoc output, so in theory you could style it however you want. It also allows people to create there own templates (Using Nunjucks) for the rendered output.

Here's a little sample

The only thing I'm still working out is resolving JSON schemas. The sample API spec I use (the original spec for this page) has some crazy nested JSON schemas and it isn't clear which parts are attributes and which are references to other objects. After implementing that it'll be pretty much done.

[RobWin]

Looks nice.
If you want to support Asciidoc and Markdown, you could use https://github.com/Swagger2Markup/markup-document-builder instead of using a Template engine.
But then people can create their own templates.

[cascer1]

That looks interesting. What kind of input does it use? I currently pass a JSON object to Nunjucks with all info.

[RobWin]

Its a standard Java builder (pattern) which consumes Strings:

MarkupDocBuilder builder = MarkupDocBuilders.documentBuilder(MarkupLanguage.ASCIIDOC)
        .documentTitle("Test title")
        .sectionTitleLevel1("Section Level 1a")
        .sectionTitleLevel2("Section Level 2a")
        .paragraph("Paragraph with long text bla bla bla bla bla")
        .listing("Source code listing")
        .boldTextLine("Bold text line b")
        .italicTextLine("Italic text line b")
        .unorderedList(Arrays.asList("Entry1", "Entry2", "Entry 2"))
        .toString();

You can even import Markdown und convert it into AsciiDoc.

Swagger2Markup has a component-based design where are document is composed of components and a component can be composed of other components. A component uses the builder to create Markdown/AsciiDoc.

A simple example is the ContactInfoComponent which renders the information about a Swagger Contact. A component consumes the parsed Swagger Java Model.

The advantage is that I don't have to maintain different templates for Markdown/AsciiDoc/Confluence Wiki.

Do you use https://github.com/raml-org/raml-java-parser?

[cascer1]

Thanks! I currently use the javascript version, but am seriously considering moving it over to java now :)

[RobWin]

👍
If you like you can copy the design of Swagger2Markup and reuse a lot of code.