Rocket-swagger

Description of the repository

This repository contains an implementation of swagger ModelConverter, used to generate OpenAPI documentation.

This implementation manages Spring reactor classes:

• Flux are converted to arrays into OpenAPI documentation.
• Mono are converted to base JSON objects into OpenAPI documentation.

Useful links for swagger

• Swagger site
• Swagger Maven plugin
• swagger-ui - used to server the generated documentation.

Maven module

• groupId: fr.irun
• artifactId: rocket-swagger

This module contains all the classes required to convert Model and Properties to OpenAPI document.

How to use

In addition with Swagger Maven plugin:

• Add swagger Maven plugin to pom.xml
• Define the entry point of this module into the configuration:

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>${swagger-maven-plugin.version}</version>
    <executions>
        <execution>
            (...)
            <configuration>
                <apiSources>
                    <apiSource>
                    (...)
                        <modelConverters>
                            fr.irun.openapi.swagger.RocketModelConverter
                        </modelConverters>
                        <outputFormats>json</outputFormats>
                    (...)
                    </apiSource>
                    </apiSources>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>${commons-lang3.version}</version>
        </dependency>
        <dependency>
            <groupId>fr.irun</groupId>
            <artifactId>rocket-swagger</artifactId>
            <version>${rocket-swagger.version}</version>
        </dependency>
    </dependencies>
</plugin>

Serve generated file using swagger-ui

After having generated the JSON file, this file can be serve using swagger-ui docker.

Prerequisites

• Docker shall be installed

Create the folder containing OpenAPI file

sudo mkdir -p /mnt/swagger
sudo chown $USER:$USER /mnt/swagger
mkdir -p /mnt/swagger/api

Pull docker imageswagger

docker pull swaggerapi/swagger-ui

Copy the generated JSON file

cp <path-to-generated-json>/swagger.json /mnt/swagger/api/

Launch the container

docker run -p 80:8080 -e SWAGGER_JSON=/api/swagger.json -v /mnt/swagger/api:/api swaggerapi/swagger-ui

Consult documentation

• The documentation is now available on http://localhost.