This example builds on the JAX-RS and ShrinkWrap example.
They both have JAX-RS resource implementations and deploy
them through a user-provided main()
programatically without
construction a .war
file during the build.
This example builds on that by adding the swagger
fraction
so that the JAX-RS API is exposed through the /swagger.json
URL.
Please raise any issues found with this example in our JIRA: https://issues.jboss.org/browse/SWARM
The project is a normal maven project with jar
packaging, not war
.
<packaging>jar</packaging>
The project adds a <plugin>
to configure wildfly-swarm-plugin
to
create the runnable .jar
.
<plugin>
<groupId>org.wildfly.swarm</groupId>
<artifactId>wildfly-swarm-plugin</artifactId>
<version>${version.wildfly-swarm}</version>
<configuration>
<mainClass>org.wildfly.swarm.examples.jaxrs.shrinkwrap.Main</mainClass>
</configuration>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
To define the needed parts of WildFly Swarm, dependencies are added
<dependency>
<groupId>org.wildfly.swarm</groupId>
<artifactId>jaxrs</artifactId>
<version>${version.wildfly-swarm}</version>
</dependency>
This dependency allows usage of ShrinkWrap APIs within the main()
in addition
to providing the JAX-RS APIs.
For the swagger dependency, the pom.xml
file needs
<dependency>
<groupId>org.wildfly.swarm</groupId>
<artifactId>swagger</artifactId>
<version>${project.version}</version>
</dependency>
Since this project deploys JAX-RS resources without a .war
being constructed, it
provides its own main()
method (specified above via the wildfly-swarm-plugin
) to
configure the container and deploy the resources programatically.
link:src/main/java/org/wildfly/swarm/examples/jaxrs/swagger/Main.java[role=include]
See: Main.java
This method constructs a new default Swarm container, which automatically initializes all fractions (or subsystems) that are available.
A SwaggerArchive
is constructed, and the JAX-RS resource class is
added to it.
The resources to be exposed by swagger.json
are specified using
a comma-separated list of package names. In this case, we only have
a single package containing JAX-RS resources that we are interested
in exposing, which is specified like so:
archive.setResourcePackages("org.wildfly.swarm.examples.jaxrs.swagger");
The Swarm container is then started with the deployment.
By default, if no JAX-RS Application
is provided a default is added
to the deployment specifying an @ApplicationPath("/")
to bind the
deployment to the root URL.
We could modify the above main()
method with:
deployment.addClass(MyApp.class);
to provide our own JAX-RS Application
, which would modify the path to be
http://localhost:8080/taco
.
The JAX-RS API in this example is exposed in the swagger.json
format
by using the annotations provided by swagger itself. See the swagger wiki
for complete documentation https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X.
In our example, we annotate the JAX-RS resource as so:
link:src/main/java/org/wildfly/swarm/examples/jaxrs/swagger/TimeResource.java[role=include]
See: TimeResource.java
By pointing your browser at http://localhost:8080/swagger.json you should see the API documented similar to this.
{
"swagger":"2.0",
"info":{"version":"1.0.0"},
"host":"localhost:8080",
"basePath":"/swagger",
"tags":[{"name":"time"}],
"schemes":["http"],
"paths": {
"/time/now": {
"get": {
"tags":["time"],
"summary":"Get the current time",
"description":"Returns the time as a string",
"operationId":"get",
"produces":["application/json"],
"parameters":[],
"responses": {
"200": {
"description":"successful operation",
"schema":{"type":"string"}
}
}
}
}
}
}
You can run it many ways:
-
mvn package && java -Dswarm.http.port=9180 -jar ./target/wf-swarm-swagger-1.0-swarm.jar &