Swagger 3 (OpenAPI 3) (swagger-ui-dist 4.15.5): Swagger Sample Application (Swagger 3, OpenAPI 3, Jersey, Jakarta, Tomcat)

Samples | Swagger Sample Application (Swagger 3, OpenAPI 3, swagger-ui-dist 4.15.5, Jersey, Jakarta, Tomcat)

The application structure
The POM file (pom.xml)
web.xml
OpenAPI document (openapi.json)
MyResourceConfig.java
Swagger/REST service: MyEntitySwaggerAPI.java
Java entity: MyEntity.java
Build and test the swagger application

The application structure
Notes:
- You can download swagger-ui-dist from: https://www.npmjs.com/package/swagger-ui-dist
```
$ wget $(npm view swagger-ui-dist dist.tarball)
```
- Extract the content of the file: swagger-ui-dist-4.15.5.tgz
- Copy the content of the directory "package" in the folder: "mtitek-swagger-samples/src/main/webapp"
```
$ cp package/* ${WORKSPACE_PATH}/mtitek-swagger-samples/src/main/webapp/
```
- Open the file "src/main/webapp/swagger-initializer.js"
  Change: url: "https://petstore.swagger.io/v2/swagger.json",
  With: url: "http://localhost:8080/mtitek-swagger-samples-1.0.0-SNAPSHOT/swagger.json",

The POM file (pom.xml)

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>mtitek.swagger.samples</groupId>
    <artifactId>mtitek-swagger-samples</artifactId>
    <packaging>war</packaging>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <maven.compiler.source>19</maven.compiler.source> <!-- maven-compiler-plugin property -->
        <maven.compiler.target>19</maven.compiler.target> <!-- maven-compiler-plugin property -->
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2-jakarta</artifactId>
            <version>2.2.8</version>
        </dependency>

        <dependency>
            <groupId>jakarta.ws.rs</groupId>
            <artifactId>jakarta.ws.rs-api</artifactId>
            <version>3.1.0</version>
        </dependency>

        <dependency>
            <groupId>jakarta.xml.bind</groupId>
            <artifactId>jakarta.xml.bind-api</artifactId>
            <version>4.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.glassfish.jersey.core</groupId>
            <artifactId>jersey-server</artifactId>
            <version>3.1.1</version>
        </dependency>

        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
            <version>3.1.1</version>
        </dependency>

        <dependency>
            <groupId>org.glassfish.jersey.inject</groupId>
            <artifactId>jersey-hk2</artifactId>
            <version>3.1.1</version>
        </dependency>

        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-json-jackson</artifactId>
            <version>3.1.1</version>
        </dependency>

        <dependency>
            <groupId>org.glassfish.jaxb</groupId>
            <artifactId>jaxb-runtime</artifactId>
            <version>4.0.2</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>

                <configuration>
                    <encoding>UTF-8</encoding>
                    <source>${maven.compiler.source}</source> <!-- optional if maven.compiler.source property is set -->
                    <target>${maven.compiler.target}</target> <!-- optional if maven.compiler.target property is set -->
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>3.3.2</version>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.5.0</version>

                <executions>
                    <execution>
                        <id>dependency-analyze</id>
                        <goals>
                            <goal>analyze</goal>
                        </goals>
                        <phase>package</phase>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-maven-plugin-jakarta</artifactId>
                <version>2.2.8</version>
                <configuration>
                    <outputFileName>swagger</outputFileName>
                    <outputPath>${project.build.directory}/${project.artifactId}-${project.version}</outputPath>
                    <outputFormat>JSON</outputFormat>
                    <resourcePackages>
                        <package>${project.groupId}</package>
                    </resourcePackages>
                    <prettyPrint>true</prettyPrint>
                    <configurationFilePath>src/main/resources/openapi.json</configurationFilePath>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>resolve</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

web.xml

src/main/webapp/WEB-INF/web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
    version="3.1">

    <filter>
        <filter-name>MyServletContainer</filter-name>

        <filter-class>org.glassfish.jersey.servlet.ServletContainer
        </filter-class>

        <init-param>
            <param-name>jakarta.ws.rs.Application</param-name>
            <param-value>mtitek.swagger.samples.MyResourceConfig</param-value>
        </init-param>

        <init-param>
             <param-name>jersey.config.servlet.filter.staticContentRegex
             </param-name>
             <param-value>^((?!/swagger/).)*$</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>MyServletContainer</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

OpenAPI document (openapi.json)

src/main/resources/openapi.json:

{
    "openAPI": {
        "info": {
            "version": "1.0",
            "title": "mtitek-swagger-samples",
            "description": "Swagger API: <b>MyEntity</b>",
            "termsOfService": "http://localhost:8080/",
            "contact": {
                "email": "contact@localhost",
                "name": "localhost",
                "url": "http://localhost:8080/"
            },
            "license": {
                "name": "localhost license",
                "url": "http://localhost:8080/"
            }
        },
        "servers": [
            {
                "url": "http://localhost:8080/mtitek-swagger-samples-1.0.0-SNAPSHOT",
                "description": "Development server"
            }
        ]
    }
}

MyResourceConfig.java

package mtitek.swagger.samples;

import jakarta.ws.rs.ext.Provider;

import org.glassfish.jersey.server.ResourceConfig;

@Provider
public class MyResourceConfig extends ResourceConfig {
    public MyResourceConfig() {
        packages(true, "mtitek.swagger.samples");
    }
}

Swagger/REST service: MyEntitySwaggerAPI.java

package mtitek.swagger.samples;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("swagger/myEntity")
@Consumes({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
public class MyEntitySwaggerAPI {
    @GET
    public Response getMyEntity() {
        MyEntity myEntity = new MyEntity();

        myEntity.setId("myEntity - id");
        myEntity.setCode("myEntity - code");
        myEntity.setDesc("myEntity - desc");

        return Response.ok(myEntity).build();
    }
}

Java entity: MyEntity.java

package mtitek.swagger.samples;

import jakarta.xml.bind.annotation.XmlAccessType;
import jakarta.xml.bind.annotation.XmlAccessorType;
import jakarta.xml.bind.annotation.XmlAttribute;
import jakarta.xml.bind.annotation.XmlElement;
import jakarta.xml.bind.annotation.XmlRootElement;
import jakarta.xml.bind.annotation.XmlTransient;

@XmlRootElement(name = "myEntity")
@XmlAccessorType(XmlAccessType.NONE)
public class MyEntity {
    @XmlAttribute(name = "id")
    private String id;

    @XmlElement(name = "code")
    private String code;

    @XmlTransient
    private String desc;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getCode() {
        return code;
    }

    public void setCode(final String code) {
        this.code = code;
    }

    public String getDesc() {
        return desc;
    }

    public void setDesc(String desc) {
        this.desc = desc;
    }
}

Build and test the swagger application
Apache Maven: mvn clean package

Apache Tomcat: deploy the war file "mtitek-swagger-samples-1.0.0-SNAPSHOT.war" in the folder "${TOMCAT_ROOT}/webapps/"

In your browser type the following URL: http://localhost:8080/mtitek-swagger-samples-1.0.0-SNAPSHOT