Skip to content

Latest commit

 

History

History
222 lines (202 loc) · 12.5 KB

README.md

File metadata and controls

222 lines (202 loc) · 12.5 KB

swagger-maven-plugin

  • Resolves project openAPI specification and saves the result in JSON, YAML or both formats. All parameters except outputFileName, outputFormat, skip, encoding and outputPath correspond to swagger configuration property with same name.

Jakarta namespace support

Since version 2.1.7 Swagger Core supports also Jakarta namespace, with a parallel set of artifacts with -jakarta suffix, providing the same functionality as the "standard" javax namespace ones. Please check Wiki for more details

Both javax and jakarta examples are provided below

Configuration example

javax namespace

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <version>2.2.29</version>
                <configuration>
                    <outputFileName>openapi</outputFileName>
                    <outputPath>${project.build.directory}/generatedtest</outputPath>
                    <outputFormat>JSONANDYAML</outputFormat>
                    <resourcePackages>
                        <package>test.petstore</package>
                    </resourcePackages>
                    <prettyPrint>TRUE</prettyPrint>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>resolve</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    <dependencies>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2</artifactId>
            <version>2.2.29</version>
        </dependency>

        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>javax.ws.rs-api</artifactId>
            <version>2.1</version>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
        </dependency>
    </dependencies>
</project>

jakarta namespace

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>io.swagger.core.v3</groupId>
                <artifactId>swagger-maven-plugin-jakarta</artifactId>
                <version>2.2.29</version>
                <configuration>
                    <outputFileName>openapi</outputFileName>
                    <outputPath>${project.build.directory}/generatedtest</outputPath>
                    <outputFormat>JSONANDYAML</outputFormat>
                    <resourcePackages>
                        <package>test.petstore</package>
                    </resourcePackages>
                    <prettyPrint>TRUE</prettyPrint>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>resolve</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    <dependencies>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2-jakarta</artifactId>
            <version>2.2.29</version>
        </dependency>

        <dependency>
            <groupId>jakarta.ws.rs</groupId>
            <artifactId>jakarta.ws.rs-api</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
            <version>5.0.0</version>
        </dependency>
    </dependencies>
</project>

Configuration example with provided Swagger configuration file

javax namespace

<project>
   <build>
       <plugins>
           <plugin>
               <groupId>io.swagger.core.v3</groupId>
               <artifactId>swagger-maven-plugin</artifactId>
               <version>2.2.29</version>
               <configuration>
                   <outputFileName>openapi</outputFileName>
                   <outputPath>${project.build.directory}/generatedtest</outputPath>
                   <configurationFilePath>${project.basedir}/src/main/resources/configurationFile.yaml</configurationFilePath>
               </configuration>
               <executions>
                   <execution>
                       <phase>compile</phase>
                       <goals>
                           <goal>resolve</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
   ...

jakarta namespace

<project>
   <build>
       <plugins>
           <plugin>
               <groupId>io.swagger.core.v3</groupId>
               <artifactId>swagger-maven-plugin-jakarta</artifactId>
               <version>2.2.29</version>
               <configuration>
                   <outputFileName>openapi</outputFileName>
                   <outputPath>${project.build.directory}/generatedtest</outputPath>
                   <configurationFilePath>${project.basedir}/src/main/resources/configurationFile.yaml</configurationFilePath>
               </configuration>
               <executions>
                   <execution>
                       <phase>compile</phase>
                       <goals>
                           <goal>resolve</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
   ...

Parameters

Parameter Description Required Default
outputPath output path where file(s) are saved true
outputFileName file name (no extension) false openapi
outputFormat file format (JSON, YAML, JSONANDYAML false JSON
skip if TRUE skip execution false FALSE
encoding encoding of output file(s) false
resourcePackages see configuration property false
resourceClasses see configuration property false
prettyPrint see configuration property false TRUE
sortOutput see configuration property false FALSE
alwaysResolveAppPath see configuration property false FALSE
skipResolveAppPath see configuration property false FALSE
openapiFilePath path to openapi file to be merged with resolved specification, see config false
configurationFilePath path to swagger config file to be merged with resolved specification, see config false
filterClass see configuration property false
readerClass see configuration property false
scannerClass see configuration property false
readAllResources see configuration property false
ignoredRoutes see configuration property false
objectMapperProcessorClass see configuration property false
defaultResponseCode see configuration property false
groupsValidationStrategy see configuration property false
validatorProcessorClass see configuration property false
modelConverterClasses see configuration property false
contextId see Context false ${project.artifactId}
openapi31 see configuration property false
schemaResolution see configuration property DEFAULT
openAPIVersion see configuration property 3.0.1/3.1.0

Since version 2.0.8, configurationFilePath parameter is available, allowing to specify a path to a swagger configuration file; If single maven configuration parameters (e.g. prettyPrint) are also defined, these will overwrite any value set in configuration file; the same applies to openapiFilePath which takes precedence over openAPI field in configuration file.

Since version 2.1.6, sortOutput parameter is available, allowing to sort object properties and map keys alphabetically. Since version 2.1.6, objectMapperProcessorClass allows to configure also the ObjectMapper instance used to serialize the resolved OpenAPI Since version 2.1.9, alwaysResolveAppPath parameter is available, allowing to trigger resolving of Application Path from annotation also not in runtime (e.g. using servlet in separate application, or in maven plugin at build time, etc) Since version 2.2.12, openapi31 parameter is available, if set to true the resolved spec will be processed into a 3.1.0 specification by resolving according to OAS 3.1 rules Since version 2.1.15, skipResolveAppPath parameter is available, allowing to skip resolving of Application Path from annotation Since version 2.2.17, defaultResponseCode parameter is available, allowing to set the code used when resolving responses with no http status code annotation Since version 2.2.24, schemaResolution parameter is available, allowing to specify how object schemas and object properties within schemas are resolved for OAS 3.0 specification Since version 2.2.28, openAPIVersion parameter is available, allowing to specify the version of the OpenAPI specification to be used for the resolved spec. Since version 2.2.29, groupsValidationStrategy parameter is available, allowing to specify the strategy for resolving Validation annotations (never, always, neverIfNoContext). Since version 2.2.29, validatorProcessorClass parameter is available, allowing to specify a custom validator processor class, implementation of io.swagger.v3.core.util.ValidatorProcessor.