PoC Swagger Plugin

This is a PoC of a Maven plugin to generate interfaces and model classes given YAML Swagger definition files (OpenAPI Spec 2.0).

The primary goal of this project is generate the classes every time you compile your code in order to be sure to implement the current API definition (fail fast approach)

The initial version of the plugin generates classes useful to implement Java Spring RestControllers but is designed to be open to other language support extensions.

Usage

Code generation is quite straightforward, the only thing to do is add the plugin definition in the Maven plugins section of your pom.xml file as follows:

<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>io.rc</groupId>
            <artifactId>poc-swagger-plugin</artifactId>
            <version>1.0-SNAPSHOT</version>
            <configuration>
                <language>custom-spring</language>
                <enableBuilderSupport>true</enableBuilderSupport>
                <codegenInfos>
                    <codegenInfo>
                        <fileName>url/or/path/to/REST-api-def.yaml</fileName>
                        <apiPackage>com.yourdomain.rest.api</apiPackage>
                        <modelPackage>com.yourdomain.rest.model</modelPackage>
                    </codegenInfo>
                </codegenInfos>
            </configuration>
            <executions>
                <execution>
                    <id>swagger-codegen</id>
                    <goals>
                        <goal>codegen</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

then you need to add some dependencies:

<!-- Spring Boot Web MVC; (spring-webmvc in case of non Boot projects) -->
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Swagger annotations -->
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-annotations</artifactId>
	<version>${swagger.annotation.version}</version>
</dependency>
<!-- Dates generated by the plugin (org.joda.time.LocalDate) -->
<dependency>
	<groupId>joda-time</groupId>
	<artifactId>joda-time</artifactId>
	<version>${joda.version}</version>
</dependency>
<!-- Jackson automatic date conversion JSON <-> LocalDate -->
<dependency>
	<groupId>com.fasterxml.jackson.datatype</groupId>
	<artifactId>jackson-datatype-joda</artifactId>
	<version>${jackson.joda.version}</version>
</dependency>

Configuration parameters

Parameter	Description	Required	Default
language	Codegen target language (*)	true	custom-spring
enableBuilderSupport	enables builder style for model classes	false	false
outputDirectory	base output directory for generated files	true	(**)
ci.fileName	YAML file path or URL	true	---
ci.apiPackage	target package for API classes	false	---
ci.modelPackage	target package for model classes	false	---
ci.skipApi	excludes API classes generation	false	false
ci.skipModel	excludes model classes generation	false	false
excludeSupportingFiles	excludes supporting files generation	false	---
excludedModel	specific model classes exclusion	false	---

ci stands for codegenInfo nested data

(*) You can use any language supported by the Swagger codegen (but only the custom-spring supports the additional features)

(**) ${project.build.directory}/generated-sources/custom-spring-codegen