Build E-Commerce Apps with Reactive Programming in Spring Boot/

...

/

Creating an API Portal

Creating an API Portal

Learn how to create an API portal to help users understand how to use the API.

We'll cover the following...

Documenting our API

After publishing a web service, we want our users to know how to use it. The best way is to stand up an API portal. Spring REST Docs can help us with this. Adding it to our project to write custom material combined with examples of our API is simple. Built upon the consistently reliable Asciidoctor documentation tool, Spring REST Docs makes it simple to capture the details we need.

To document our API, we can add the following to our pom.xml file:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <executions>
        <execution>
            <id>generate-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
        </dependency>
    </dependencies>
</plugin>
Configuring Maven to generate snippets of web service interaction

The asciidoctor-maven-plugin provides the means to transform AsciiDoc (.adoc) files into HTML. As we’ll soon see, Spring REST Docs provides a mechanism to generate key bits of AsciiDoc automatically. When this plugin runs, its HTML results will be in target/generated-docs.

Creating index.adoc

By default, Spring REST Docs expects AsciiDoc material in the /src/main/asciidoc file, so we need to create src/main/asciidoc/index.adoc. With this file created, we can draft the opening lines of our new API portal.

= Hacking with Spring Boot API Portal
When you create a web service, developers want to see how to use it. Thanks to Spring
REST Docs, you can generate all the interactions needed via test cases that in turn
generate readable documentation. A match made in heaven, or at least, in your IDE.
By running the following request...
Writing first bits of material for our API portal

So far, so good. It’s not much, but there’s more to come.

Note: AsciiDoc is the standard, and Asciidoctor is a Ruby project that implements the AsciiDoc standard. Thanks to its strong community and the magic of JRuby, there are many Java utilities, including AsciidoctorJ, as well as support in both Maven and Gradle.

We’ll need many examples to write good API docs. We can immediately start writing them by hand in index.adoc. But there’s a much better way to connect this to our building API.

To get started, we’ll need some test utilities, such as following:

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-webtestclient</artifactId>
    <scope>test</scope>
</dependency>
Adding Spring REST Docs support for WebTestClient to our build

This test-scoped dependency, spring-restdocs-webtestclient, provides extra hooks to Spring Framework’s WebTestClient ...