REST-based Microservice Documentation

Copies of this entity may be made for Your own use and for distribution to others, provided that You do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

If You find errors or omissions in this entity, please don’t hesitate to submit an issue or open a pull request with a fix.

REST-based microservice documentation describes rules of interaction with REST-based microservices for fast and easy integration with them.

Currently, the RxMicro framework only supports specialized documentation format based on the AsciiDoc format.

1. Basic Usage

Default settings allow You to generate REST-based microservice documentation using minimal configurations.
(This advantage is achieved through close integration with other RxMicro modules.)

1.1. Min Settings

To generate REST-based microservice documentation during the compilation of the microservice project, the following two steps must be done:

Add the rxmicro-documentation-asciidoctor dependency to pom.xml of the microservice project:

<dependency>
    <groupId>io.rxmicro</groupId>
    <artifactId>rxmicro-documentation-asciidoctor</artifactId>
    <version>${rxmicro.version}</version>
</dependency>

Add the rxmicro.documentation.asciidoctor module to the module-info.java descriptor of the microservice project:

module examples.documentation.asciidoctor.quick.start {
    requires rxmicro.rest.server.netty;
    requires rxmicro.rest.server.exchange.json;
    requires static rxmicro.documentation.asciidoctor; (1)
}

1	The `rxmicro.documentation.asciidoctor` must be added using the `static` modifier. (For more information on the benefits of the `static` modifier, refer to the Section 1.3, “`Asciidoctor-dependency-plugin` Settings”.)

After performing these steps during compiling the microservice project, the RxMicro Annotation Processor will generate the ExamplesDocumentationAsciidoctorQuickStartDocumentation.adoc file. The generated file will contain REST-based microservice documentation in the AsciiDoc format, and by default will be located in the ./src/main/asciidoc folder.

In terms of the version control system, the ./src/main/asciidoc folder is the source code, so it will be controlled by this system. Therefore, if REST-based microservice documentation is to be dynamically generated, it is necessary to:

specify that files in the ./src/main/asciidoc folder must be ignored by the version control system;
or configure the rxmicro.documentation.asciidoctor module, so that it generates REST-based microservice documentation in another folder, for example in the target/docs.
(To configure the folder in which REST-based microservice documentation should be generated, refer to the core.html.)

Using the ./src/main/asciidoc folder by default provides the following benefits:

The asciidoctor-maven-plugin, which converts the AsciiDoc format to HTML or PDF , by default reads files from the ./src/main/asciidoc folder.
Automatic building of REST-based microservice documentation can be used as an initial version of the document. After formation of the initial version, the generation can be disabled and all changes to the documentation will be made manually by the developer and stored in the version control system.
Compared to the previous version, a more efficient way to keep REST-based microservice documentation up to date is to divide all documentation into fragments. Static fragments (business task description, charts and figures) will be created manually by the developer. Dynamic fragments will be generated by the RxMicro Annotation Processor at each project compilation. As a result, a final document containing static and dynamic fragments will be compiled from these fragments.
(When using this approach, do not forget to add the all dynamic fragments to ignore list for Your version control system!)

1.2. `Asciidoctor-maven-plugin` Settings

The asciidoctor-maven-plugin plugin allows You to convert documentation from the AsciiDoc format to HTML, PDF and other formats.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId> (1)
    <version>${asciidoctor-maven-plugin.version}</version>
    <executions>
        <execution>
            <id>output-html5</id>
            <phase>package</phase> (2)
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend> (3)
                <sourceHighlighter>highlight.js</sourceHighlighter> (4)
                <preserveDirectories>true</preserveDirectories>
                <relativeBaseDir>true</relativeBaseDir>
                <attributes> (5)
                    <icons>font</icons>
                    <pagenums/>
                    <toclevels>3</toclevels>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

1	The latest stable version of the `asciidoctor-maven-plugin`.
2	The `asciidoctor-maven-plugin` must convert REST-based microservice documentation at the `package` phase.
3	Using the `backend` directive, You can specify in which format the `AsciiDoc` document should be converted.
4	If the `AsciiDoc` document contains examples of source code in a programming language, You need to add the js library for highlighting the syntax of that language.
5	Using the `attributes` directive, it is possible to override the attributes of the `AsciiDoc` document.

For more information about the asciidoctor-maven-plugin plugin features, refer to the documentation:

https://asciidoctor.org/docs/asciidoctor-maven-plugin/

1.3. `Asciidoctor-dependency-plugin` Settings

REST-based microservice documentation is generated during the compilation process, therefore the libraries used to configure the REST-based microservice documentation generation process are not required in runtime. Therefore, the maven-dependency-plugin should not copy artifacts related to the generation of REST-based microservice documentation to the lib folder:

<plugin>
    <artifactId>maven-dependency-plugin</artifactId>
    <version>${maven-dependency-plugin.version}</version>
    <executions>
        <execution>
            <id>copy-dependencies</id>
            <phase>package</phase>
            <goals>
                <goal>copy-dependencies</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.directory}/lib</outputDirectory>
                <includeScope>compile</includeScope>
                <excludeArtifactIds> (1)
                    rxmicro-documentation,
                    rxmicro-documentation-asciidoctor
                </excludeArtifactIds>
            </configuration>
        </execution>
    </executions>
</plugin>

1	The `rxmicro-documentation` and `rxmicro-documentation-asciidoctor` artifacts are required only during the compilation process.

In order that in runtime no errors occur when excluding the artifacts required for REST-based microservice documentation generation, it is required to use the static modifier in the module-info.java descriptor: requires static rxmicro.documentation.asciidoctor;.

Without this modifier the following error will occur when starting the microservice: Module rxmicro.documentation.asciidoctor not found!

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

ExamplesDocumentationAsciidoctorQuickStartDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-quick-start

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

2. `RxMicro Annotations`

The RxMicro framework supports the following RxMicro Annotations:

Table 1. Supported `RxMicro Annotations`.
Annotation	Description
`@Author`	Denotes the author of the generated REST-based microservice documentation. (Allows You to override the author specified in the `developer` directive to `pom.xml`.)
`@BaseEndpoint`	Denotes the basic endpoint in the generated REST-based microservice documentation. (Allows You to override the basic endpoint specified in the `url` directive to `pom.xml`.)
`@Description`	Denotes the description of the generated REST-based microservice documentation. (Allows You to override the description specified in the `description` directive to `pom.xml`.) In addition to the description of all REST-based microservice documentation, this annotation also allows You to specify a description of separate elements: sections, model fields, etc.
`@DocumentationDefinition`	A composite annotation that specifies the settings for generating a whole document.
`@DocumentationVersion`	Denotes the version of REST-based microservice in the generated REST-based microservice documentation. (Allows You to override the version of REST-based microservice specified in the `version` directive to `pom.xml`.)
`@Example`	Denotes the model field value used as an example in the generated REST-based microservice documentation.
`@IncludeDescription`	Denotes the AsciiDoc fragment to be imported into the generated REST-based microservice documentation. In addition to the description of all REST-based microservice documentation, this annotation also allows You to specify the AsciiDoc fragment for separate elements: sections, model fields, etc.
`@IntroductionDefinition`	A composite annotation that specifies the settings for generating the `Introduction` section.
`@License`	Denotes the license of REST-based microservice in the generated REST-based microservice documentation. (Allows You to override the license of REST-based microservice specified in the `license` directive to `pom.xml`.)
`@ModelExceptionErrorResponse`	Denotes the exception class to be analyzed by the `RxMicro Annotation Processor` for generating the unsuccessful HTTP response description of REST-based microservice.
`@ResourceDefinition`	A composite annotation that specifies the settings for generating the `ResourceDefinition` section.
`@ResourceGroupDefinition`	A composite annotation that specifies the settings for generating the `ResourceGroupDefinition` section.
`@SimpleErrorResponse`	Contains metadata about the unsuccessful HTTP response of REST-based microservice.
`@Title`	Denotes the name of the generated REST-based microservice documentation. (Allows You to override the name of the generated REST-based microservice documentation specified in the `name` directive to `pom.xml`.)
`@DocumentAttributes`	Allows You to specify AsciiDoc attributes for the generated REST-based microservice documentation.

3. `@Example` and `@Description` Usage

Using the @Example annotation, the developer can specify the data that is as close to the real data as possible, which will be used to build examples of usage in REST-based microservice documentation.

Using the @Description annotation, the developer can specify the detailed description of separate model fields to be used in building REST-based microservice documentation.

public final class Echo {

    @Example("EchoExample")
    @Description("EchoDescription")
    String echo;
}

final class MicroService {

    @GET("/")
    @POST("/")
    @POST(value = "/", httpBody = false)
    CompletableFuture<Echo> echo(final Echo echo) {
        return completedFuture(echo);
    }
}

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

ExamplesDocumentationAsciidoctorEchoDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-echo

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

4. Sections Customization

Using the following composite annotations:

the developer can regroup standard sections of REST-based microservice documentation, as well as add his own fragments as sections.

@DocumentationDefinition(
        withGeneratedDate = false,
        introduction = @IntroductionDefinition(
                sectionOrder = {
                        IntroductionDefinition.Section.LICENSES,
                        IntroductionDefinition.Section.SPECIFICATION,
                        IntroductionDefinition.Section.CUSTOM_SECTION
                },
                customSection = {
                        "${PROJECT-DIR}/src/main/asciidoc/_fragment/" +
                                "custom-introduction-content.asciidoc"
                },
                includeMode = IncludeMode.INLINE_CONTENT
        ),
        resourceGroup = @ResourceGroupDefinition(
                sectionOrder = {
                        ResourceGroupDefinition.Section.CUSTOM_SECTION
                },
                customSection = {
                        "${PROJECT-DIR}/src/main/asciidoc/_fragment/" +
                                "custom-resource-group-content.asciidoc"
                },
                includeMode = IncludeMode.INLINE_CONTENT
        ),
        resource = @ResourceDefinition(
                withInternalErrorResponse = false,
                withJsonSchema = false,
                withRequestIdResponseHeader = false,
                withQueryParametersDescriptionTable = false,
                withBodyParametersDescriptionTable = false
        )
)
module examples.documentation.asciidoctor.custom.sections {
    requires rxmicro.rest.server.netty;
    requires rxmicro.rest.server.exchange.json;
    requires static rxmicro.documentation.asciidoctor;
}

Besides generating the final AsciiDoc document, the RxMicro Annotation Processor allows You to generate separate dynamic fragments.

For more information on this feature, check out the following example:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-custom-sections

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

ExamplesDocumentationAsciidoctorCustomSectionsDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-custom-sections

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

5. Integration with `rxmicro.validation` Module

The rxmicro.documentation.asciidoctor module is integrated with the rxmicro.validation module. Thanks to this integration, when building the REST-based microservice documentation, the RxMicro framework analyzes all available built-in constraints for automatic generation of model fields description.

@DocumentationDefinition(
        introduction = @IntroductionDefinition(sectionOrder = {}),
        withGeneratedDate = false
)
module examples.documentation.asciidoctor.validation {
    requires rxmicro.rest.server.netty;
    requires rxmicro.rest.server.exchange.json;
    requires rxmicro.validation;
    requires static rxmicro.documentation.asciidoctor;
}

final class MicroService {

    @PUT("/")
    void consume(final @Phone String phone) { (1)
        // do something
    }
}

1	The `phone` parameter must be validated via built-in constraint for phones.

Thus, when building the REST-based microservice documentation, the RxMicro framework will automatically generate a description for the phone parameter:

Figure 1. The phone field description, formed based on built-in constraints analysis

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

ExamplesDocumentationAsciidoctorValidationDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-validation

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

6. REST-based Microservice Metadata Configuration

To obtain metadata while building REST-based microservice documentation, the RxMicro framework can use:

The pom.xml file;
The rxmicro.documentation module annotations.

The REST-based microservice metadata is:

the REST-based microservice name;
the REST-based microservice description;
the REST-based microservice version;
the list of licenses that cover the REST-based microservice;
the list of REST-based microservice developers;
the REST-based microservice basic endpoint.

6.1. Using `pom.xml`

To specify the metadata needed to generate the REST-based microservice documentation, You can use the pom.xml file

<project>
    <name>Metadata Pom Xml</name>
    <description>*Project* _Description_</description>
    <developers>
        <developer>
            <name>Richard Hendricks</name>
            <email>richard.hendricks@piedpiper.com</email>
        </developer>
        <developer>
            <name>Bertram Gilfoyle</name>
            <email>bertram.gilfoyle@piedpiper.com</email>
        </developer>
        <developer>
            <name>Dinesh Chugtai</name>
            <email>dinesh.chugtai@piedpiper.com</email>
        </developer>
    </developers>
    <url>https://api.rxmicro.io</url>
    <licenses>
        <license>
            <name>Apache License 2.0</name>
            <url>https://github.com/rxmicro/rxmicro/blob/master/LICENSE</url>
        </license>
    </licenses>
</project>

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

MetadataPomXmlDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-metadata-pomxml

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

6.2. Using Annotations

To specify the metadata needed to generate the REST-based microservice documentation, You can use the rxmicro.documentation module annotations.

@Title("Metadata Annotations")
@Description("*Project* _Description_")
@DocumentationVersion("0.0.1")
@Author(
        name = "Richard Hendricks",
        email = "richard.hendricks@piedpiper.com"
)
@Author(
        name = "Bertram Gilfoyle",
        email = "bertram.gilfoyle@piedpiper.com"
)
@Author(
        name = "Dinesh Chugtai",
        email = "dinesh.chugtai@piedpiper.com"
)
@BaseEndpoint("https://api.rxmicro.io")
@License(
        name = "Apache License 2.0",
        url = "https://github.com/rxmicro/rxmicro/blob/master/LICENSE"
)
@DocumentationDefinition(
        introduction = @IntroductionDefinition(
                sectionOrder = {
                        IntroductionDefinition.Section.BASE_ENDPOINT,
                        IntroductionDefinition.Section.LICENSES
                }
        ),
        resource = @ResourceDefinition(
                withInternalErrorResponse = false
        ),
        withGeneratedDate = false
)
module examples.documentation.asciidoctor.metadata.annotations {
    requires rxmicro.rest.server.netty;
    requires rxmicro.rest.server.exchange.json;
    requires static rxmicro.documentation.asciidoctor;
}

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

MetadataAnnotationsDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-metadata-annotations

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

7. Error Documentation

To describe unsuccessful HTTP responses, the rxmicro.documentation module provides two annotations:

Unresolved directive in ../_fragment/_project-documentation/errors.adoc - include::../../../../../../examples/group-documentation-asciidoctor/documentation-asciidoctor-errors/src/main/java/io/rxmicro/examples/documentation/asciidoctor/errors/ProxyMicroService.java[tags=content]

1	The `@SimpleErrorResponse` annotation allows You to explicitly specify the HTTP response description.
2	The `status` parameter describes the HTTP status code.
3	The `description` parameter describes the text description.
4	The `exampleErrorMessage` parameter denotes the value used as an example in the generated REST-based microservice documentation.
5	The `@ModelExceptionErrorResponse` annotation allows You to specify the exception class of the standard
6	or custom type.

When using the custom exception type, this class contains all necessary parameters for building REST-based microservice documentation:

Unresolved directive in ../_fragment/_project-documentation/errors.adoc - include::../../../../../../examples/group-documentation-asciidoctor/documentation-asciidoctor-errors/src/main/java/io/rxmicro/examples/documentation/asciidoctor/errors/model/NotAcceptableException.java[tags=content]

1	The required `STATUS_CODE` static field describes the HTTP status code.
2	The `@Description` annotation describes the text description.
3	The `@Example` annotation describes the value used as an example in the generated REST-based microservice documentation.

The custom exception class can contain not string parameter(s). For such classes the RxMicro framework returns custom JSON model instead of standard one.

Unresolved directive in ../_fragment/_project-documentation/errors.adoc - include::../../../../../../examples/group-documentation-asciidoctor/documentation-asciidoctor-errors/src/main/java/io/rxmicro/examples/documentation/asciidoctor/errors/model/CustomErrorModelException.java[tags=content]

1	The `@Description` annotation describes the text description.
2	The required `STATUS_CODE` static field describes the HTTP status code.
3	The custom field can contain `@Example` and `@Description` annotations.
4	The custom field(s) must be initialized via constructor.
5	For custom exception classes with custom field(s) the RxMicro Annotation Processor does not generate `Writer`, so You must override the `getResponseData` method manually!
6	Overridden method must return values from all declared fields at custom exception class.

If RX_MICRO_STRICT_MODE option is enabled, the RxMicro Annotation Processor validates the overidden getResponseData method and throws compilation error if some field values not returned!

When compiling a project, the RxMicro framework will generate the following project documentation according to the settings of the rxmicro.documentation.asciidoctor module defined in this section:

ExamplesDocumentationAsciidoctorErrorsDocumentation.html

The project source code used in the current subsection is available at the following link:

https://github.com/rxmicro/rxmicro-usage/tree/master/examples/group-documentation-asciidoctor/documentation-asciidoctor-errors

When compiling, the RxMicro framework searches for RxMicro Annotations in the source code and generates additional classes necessary for the integral work of the microservice.

When changing the RxMicro Annotations in the source code, DON’T FORGET to recompile the ALL source code, not just the changed file, for the changes to take effect: mvn clean compile.

Validation

Home

Postgre SQL Data Repositories