Use swagger-maven-plugin in Ivy 8

Lyn

Does anybody use swagger-maven-plugin to generate REST API documentation in Ivy 8?
I workaround with this plugin, Its not completely work. The file was generated with basic information but the paths section does not appear.
This is my pom.xml

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<groupId>swagger.demos</groupId>
	<artifactId>swagger-demos</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<packaging>iar</packaging>
	<dependencies>
		<!-- https://mvnrepository.com/artifact/org.glassfish.jersey.core/jersey-client -->
		<dependency>
			<groupId>org.glassfish.jersey.core</groupId>
			<artifactId>jersey-client</artifactId>
			<version>2.27</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/org.glassfish.jersey.core/jersey-common -->
		<dependency>
			<groupId>org.glassfish.jersey.core</groupId>
			<artifactId>jersey-common</artifactId>
			<version>2.27</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/org.glassfish.jersey.media/jersey-media-multipart -->
		<dependency>
			<groupId>org.glassfish.jersey.media</groupId>
			<artifactId>jersey-media-multipart</artifactId>
			<version>2.27</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
		<dependency>
			<groupId>io.swagger.core.v3</groupId>
			<artifactId>swagger-annotations</artifactId>
			<version>2.0.0</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-core -->
		<dependency>
			<groupId>io.swagger.core.v3</groupId>
			<artifactId>swagger-core</artifactId>
			<version>2.0.0</version>
			<exclusions>
				<exclusion>
					<artifactId>jsr311-api</artifactId>
					<groupId>javax.ws.rs</groupId>
				</exclusion>
				<exclusion>
					<artifactId>commons-lang3</artifactId>
					<groupId>org.apache.commons</groupId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>ch.ivyteam.ivy.addons</groupId>
			<artifactId>doc-factory</artifactId>
			<version>8.0.3</version>
			<type>iar</type>
		</dependency>
		<dependency>
			<groupId>javax.xml.bind</groupId>
			<artifactId>jaxb-api</artifactId>
			<version>2.3.1</version>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>com.axonivy.ivy.ci</groupId>
				<artifactId>project-build-plugin</artifactId>
				<version>8.0.7</version>
				<extensions>true</extensions>
			</plugin>
			<plugin>
				<artifactId>maven-dependency-plugin</artifactId>
				<executions>
					<execution>
						<id>copy-libraries-to-libs-folder</id>
						<phase>validate</phase>
						<goals>
							<goal>copy-dependencies</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<outputDirectory>${basedir}/libs</outputDirectory>
					<stripVersion>true</stripVersion>
					<includeScope>compile</includeScope>
					<excludeTypes>iar</excludeTypes>
					<excludeTransitive>true</excludeTransitive>
					<overWriteSnapshots>true</overWriteSnapshots>
					<overWriteReleases>true</overWriteReleases>
				</configuration>
			</plugin>
			<!-- Swagger maven plugin -->
			<plugin>
				<groupId>com.github.kongchen</groupId>
				<artifactId>swagger-maven-plugin</artifactId>
				<version>3.1.8</version>
				<executions>
					<execution>
						<phase>compile</phase>
						<goals>
							<goal>generate</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<!-- Include the classpath of engine and project itself to this plugin. -->
					<additionalDependency>
						<additionalClassPath>${ivy.engine.core.classpath},${basedir}/classes</additionalClassPath>
					</additionalDependency>
					<!-- Define some basic information for plugin, please read at https://github.com/kongchen/swagger-maven-plugin -->
					<apiSources>
						<apiSource>
							<springmvc>false</springmvc>
							<locations>
								<location>de.eon.demo.swagger.api</location>
							</locations>
							<schemes>http,https</schemes>
							<!-- Host and path to resful api. For engine, designer should be replaced by application name that you deploy this project to -->
							<host>localhost:8081</host>
							<basePath>/ivy/api/designer</basePath>
							<info>
								<title>External Dossier Service</title>
								<version>v1</version>
								<description>Transfer of customer data in a new onboarding dossier.</description>
								<contact>
									<email>info@axonivy.com</email>
									<name>Axon Fintech</name>
									<url>http://www.axonfintech.com/</url>
								</contact>
							</info>
							<!-- Format & location of output file -->
							<outputFormats>yaml</outputFormats>
							<templatePath>${basedir}/swagger-templates/strapdown.html.hbs</templatePath>
							<swaggerDirectory>${basedir}/webContent/generated/</swaggerDirectory>
							<outputPath>${basedir}/webContent/generated/document.html</outputPath>
							<swaggerFileName>api-documentation</swaggerFileName>
							<attachSwaggerArtifact>true</attachSwaggerArtifact>
							<securityDefinitions>
								<securityDefinition>
									<name>basicAuth</name>
									<type>basic</type>
								</securityDefinition>
							</securityDefinitions>
						</apiSource>
					</apiSources>
				</configuration>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-war-plugin</artifactId>
				<version>2.1.1</version>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.1</version>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Thanks

Reguël Wermelinger

I've never seen it used with ivy-8.
However, with LTS 10 you get swagger openapi.json generation out-of the box. And also the swagger-ui to explore the APIs is part of the standard distribution. So I'd consider an upgrade to LTS 10.
See https://dev.axonivy.com/news/9.2 where we praise the out-of-the-box OpenAPI integration.

Meanwhile you could also try to do a workaround:

e.g. deploy our projects to an ivy-10 engine during the build
get the openapi.json

This could work for simple REST interfaces, as in theory ivy 8 projects can be deployed to an ivy 10 engine. The steps to make the project basically compliant will be done automatically during deployment. However, if you are referring APIs that no longer exist under 10, runtime errors will occur as the compiled classes will remain untouched.