swagger2asciidoc about spring-restdocs HOT 15 CLOSED

Thanks for pointing me to your project. It's an interesting approach to the problem and one that I hadn't thought of before.

I'm coming at this as someone who isn't a fan of Swagger for a variety of reasons. I covered them in a recent webinar (it's on YouTube), but I'll try to summarise them here:

1. It doesn't support hypermedia. I like to avoid the religious debate about what is and is not REST, but I do think that a tool for documenting RESTful APIs really ought to support (but not require) the use of hypermedia.
2. The general approach for generating the metadata is to harvest it from the implementation. Unfortunately, I think this approach is fundamentally flawed as it requires that the tool performing the harvesting understands every little detail of the implementation and the framework that it's been built with. That's a near-impossible task and, at the very least, means that the tool will constantly be playing catch up. They offer a raft of annotations to work around (some of) these limitations but you then end up repeating yourself as you have to configure Swagger and the framework with which you're building your API.
3. Annotations are a really unpleasant way to write documentation and Swagger leans on them heavily for its operation descriptions, parameter descriptions, etc.
4. I don't like the format/layout of the documentation that Swagger produces. For example, it places far too much focus on URIs and wastes space repeating information about HTTP status codes which, unless you're doing something off the wall, probably don't need to be mentioned at all. It also doesn't provide any where for you to provide an overview of the API (here's GitHub's, for example).

Problems 1, 2, and 3 are pretty much out of your control. What you've done does a nice job of tackling a large chunk of 4. If it were me I'd filter out the HTTP status codes and probably the consumes/produces MIME types too (assuming they're consistent across the whole API).

from spring-restdocs.

This got me thinking about a possible situation. Assume I have a suite of applications that currently uses swagger for all it's documentation. I would like to be able to improve the documentation, but there may not be time nor budget for making huge sweeping changes in our documentation process.

What is the conceptual approach that a user of either of these projects should take towards adoption into or migration away from such an environment?

Would I be able to gradually incorporate the product, or would I have to make sweeping changes to get any value from them?

Assuming I cannot move completely away from swagger, would either project be able to add hypermedia support?

from spring-restdocs.

Thanks for your comments.
I agree to all your points. I mainly created the swagger2asciidoc project to be able to reverse engineer an existing Annotation-based API documentation to a "markup language"-based documentation,

from spring-restdocs.

@RobWin Sorry, I think it was missing the wood for the trees

@Pytry I think you could introduce either spring-restdocs or swagger2asciidoc somewhat gradually.

You could use spring-restdocs to introduce some new getting started documentation that walks people through the steps to perform certain tasks with your API. Both of the samples contain such documentation. This approach is quite nice as the two different pieces of documentation are totally separate so there's no joint maintenance to worry about.

Another option would be to use @RobWin's project to produce some documentation in Asciidoctor based on all your existing Swagger-based documentation. This document could then be checked into source control and evolved over time. You might want to start by adding an overview section that describes some of the common features of all of your API's resources. Or you could gradually introduce the use of spring-restdocs to add some example requests and responses. If the API evolves, you'll have some joint maintenance to do for a while to keep the native Swagger documentation and the Asciidoctor conversion in step, but that's an inevitable consequence of a gradual migration.

from spring-restdocs.

I plan to use swagger2asciidoc and spring-restdocs as follows:

• Migrate Annotation-Based documentation to AsciiDoc.
• Use spring-restdocs to generate request and response examples
• Use jackson-module-jsonSchema to generate JSON schema of the domain model on the fly
• Use JAXB to generate XML schema of the domain model on the fly
• Include the generated AsciiDoc files into the main AsciiDoc documentation.

from spring-restdocs.

Hello @wilkinsona
I've integrated spring-restdocs now. I'm able to include the generated examples from spring-restdocs into the generated AsciiDoc document.

Let's say I have a Swagger-annotated Controller method with a ApiOperation value "Create a quota"

@ApiOperation(value = "Create a quota.", notes =  "Create a quota allows bla bla bla bla")
public void createMailStorageQuota(@ApiParam(name = "MailStorageQuota", value = "MailStorageQuota", required = true) @RequestBody MailStorageQuota mailStorageQuota) {
}

I'm using spring-restdocs in combination with https://github.com/jayway/rest-assured to test the Controller.
The target folder of the generated request and response example files must be "create_a_quota".

given().contentType(ContentType.XML).body(storageQuota).resultHandlers(document("create_a_quota")).
when().put("/quotas").
then().statusCode(204);

The output directory is configured as follows:

io.restdocumented.outputDir = docs/generated

The Swagger2MarkupConverter must know the output directory of spring-restdocs.

Swagger2MarkupConverter.from("http://localhost:8080/api-docs").
                withExamples("docs/generated").build()
                .intoFolder("src/docs/asciidoc");

The Swagger2MarkupConverter searches for a Swagger ApiOperation with value: "Create a quota" in a folder called "docs/generated/create_a_quota" for example files and includes the request.asciidoc and response.asciidoc files, if they are available.

Now my question: Could you please enhance spring-restdocs so that it can generate AsciiDoc and/or Markdown files? Maybe configurable via gradle? That would be great. In that way, I could generated AsciiDoc and Markdown documents with examples.

Kind regards,

Robert Winkler

PS:
The Converter can also include JSON and XML Schema files.

Swagger2MarkupConverter.from("http://localhost:8080/api-docs").
                withMarkupLanguage(MarkupLanguage.MARKDOWN).
                withExamples("docs/generated").withSchemas("docs/schemas").build()
                .intoFolder("src/docs/markdown");

I create the Schemas files in Unit-Tests as follows:

        RestDocumented restDocumented = RestDocumented.fromProperties();
        restDocumented.documentJsonSchema(MailStorageQuota.class, "docs/schemas");
        restDocumented.documentXmlSchema(MailStorageQuota.class, "docs/schemas");

from spring-restdocs.

I'd always envisaged the output format being pluggable and there's a (somewhat incomplete) abstraction around DocumentationWriter in the current code. It's incomplete as there's no way to plug in a different DocumentationWriter.

Adding Markdown had seemed like the next obvious format after Asciidoctor, but I've yet to find a Markdown-based toolchain that works well with Maven and Gradle. I see you've got an example that uses MkDocs in your README but, as far as I know, it requires Python. Are you aware of anything for Markdown that has the same level of integration into the JVM's build tools as Asciidoctor does?

from spring-restdocs.

pegdown is pretty good
https://github.com/sirthias/pegdown

from spring-restdocs.

@wilkinsona @glaforge
Have a look at https://github.com/jbake-org/jbake to generate a HTML documentation with Markdown or AsciiDoc. The project can be compared to Jekyll, but runs on the JVM. The project Griffon uses JBake for its documentation: http://new.griffon-framework.org/

Then there is a nice Markdown Gradle plugin which uses Pegdown.
https://github.com/aalmiray/markdown-gradle-plugin

For generating AsciiDoc and Markdown output you can reuse my DocumentBuilder from Swagger2MarkupConverter. If you like, i can extract it and make it an own library.
Have a look at it. It can also create Tables and source code listings.

DocumentBuilder builder = DocumentBuilders.documentBuilder(MarkupLanguage.ASCIIDOC);
builder.documentTitle("Test title").textLine("Text line").writeToFile("/tmp", "test.adoc", StandardCharsets.UTF_8);

DocumentBuilder builder = DocumentBuilders.documentBuilder(MarkupLanguage.MARKDOWN);
builder.documentTitle("Test title").source("Java code", "java").paragraph("Long text paragaph with line breaks").writeToFile("/tmp", "test.adoc", StandardCharsets.UTF_8);

from spring-restdocs.

Btw. when you use http://www.mkdocs.org/ and http://readthedocs.org/ together, yon don't have to install Python. Only if you want to preview your changes on a local server.

I love the readthedocs theme:
http://supervisorclusterctl.readthedocs.org/

from spring-restdocs.

@glaforge @RobWin Thanks, both. Those look like some excellent options. I've opened #19 to add support for generating Markdown.

@RobWin Thanks for the pointer to your DocumentBuilder. Thanks for the offer to extract it into a library, but I'd like to keep this project's dependencies as minimal as possible.

from spring-restdocs.

Then feel free to copy what you need :)

from spring-restdocs.

MarkupDocBuilder is extracted now.
https://github.com/RobWin/markup-document-builder

from spring-restdocs.

@Pytry Have a look at https://github.com/RobWin/swagger2markup now

from spring-restdocs.

@wilkinsona I fully agree with using annotations for documentation purposes... we have been using https://github.com/conorroche/swagger-doclet (javadoc doclet) instead for this purpose and this way our JAX-RS endpoints have the javadoc and the swagger doc in sync... And documentation is where it belongs.....

from spring-restdocs.