repository·master·Indexed 27 days ago
https://github.com/swagger-api/swagger-coreA Java-based implementation of the OpenAPI Specification that enables developers to integrate OpenAPI capabilities into Java APIs. It supports JAX-RS2 using both javax and jakarta namespaces and provides support for OpenAPI 3.1 since version 2.2.0. The project includes the swagger-gradle-plugin and swagger-maven-plugin for resolving OpenAPI specifications, as well as a Bill of Materials (swagger-bom) for simplified dependency management.
javax and jakarta namespaces.The swagger-maven-plugin resolves your project's OpenAPI specification and saves the result in JSON, YAML, or both formats.
Most configuration parameters correspond directly to the swagger configuration properties. Specific plugin-level parameters include:
outputFileName: The name of the generated file.outputFormat: The format of the output (e.g., JSON, YAML, or JSONANDYAML).skip: Whether to skip the resolution process.encoding: The character encoding for the output files.outputPath: The directory where the files will be saved.To build Swagger Core locally, ensure you have Java 11, Apache Maven 3.0.4 or greater, and Jackson 2.4.5 or greater installed and available in your $PATH.
For the first time building locally, run:
mvn -NFor subsequent builds, use:
mvn install# first time building locally
mvn -N
# Subsequent builds
mvn installThe openApiFile parameter allows you to point to a YAML or JSON file representing an input specification. This file will be merged with the resolved specification. This is typically used to add metadata like the info section (title, version, description, etc.) to the generated output.
openapi: 3.0.4
info:
version: '1.0'
title: Swagger Pet Sample App Config File
description: 'This is a sample server Petstore server.'
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.htmlSince version 2.1.7, Swagger Core provides parallel sets of artifacts to support different Java namespaces.
javax namespace, use the unsuffixed artifacts.jakarta namespace, use the artifacts with the -jakarta suffix.Both sets provide the same functionality.
Official sample applications containing various integrations and configurations for Swagger Core have been moved to a dedicated repository. You can find them at the following location:
For projects using the jakarta namespace, use the swagger-maven-plugin-jakarta artifact instead of the standard plugin. The configuration structure remains the same, allowing you to define outputFileName, outputPath, and configurationFilePath.
<project>
<build>
<plugins>
<plugin>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin-jakarta</artifactId>
<version>2.2.52</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>
...
</project>Depending on your Gradle version, use one of the following installation methods:
Use the plugins block in your build.gradle file.
Note: Gradle 1.x and 2.x up to 3.1 are only supported with plugin versions up to 2.0.9. For newer versions, use the Gradle 3.2+ method.
Use the buildscript block to add the plugin to your classpath and then apply it.
// Gradle 3.2+
plugins {
id "io.swagger.core.v3.swagger-gradle-plugin" version "2.2.52"
}
// Gradle 1.x and 2.0 (up to version 2.0.9)
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "io.swagger.core.v3:swagger-gradle-plugin:2.2.52"
}
}
apply plugin: "io.swagger.core.v3.swagger-gradle-plugin"To use the swagger-maven-plugin with the javax namespace, add the plugin to your Maven build configuration. You can specify the output file name, output path, and a path to an external Swagger configuration file. The resolve goal should be bound to a lifecycle phase like compile.
<project>
<build>
<plugins>
<plugin>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.2.52</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>
...
</project>To generate code coverage reports for the project, run the Maven verify command. This will produce coverage reports within each module. To view the report, open the generated index.html file in your web browser.
mvn clean verifyIn Gradle, use platform to import the swagger-bom. This allows you to declare dependencies for both javax and jakarta namespaces without specifying versions.
Example for javax artifacts:
implementation("io.swagger.core.v3:swagger-annotations")
implementation("io.swagger.core.v3:swagger-core")Example for jakarta artifacts:
implementation("io.swagger.core.v3:swagger-annotations-jakarta")
implementation("io.swagger.core.v3:swagger-core-jakarta")dependencies {
implementation(platform("io.swagger.core.v3:swagger-bom:${swaggerOpenapiv3Version}))
// javax artifacts — no version needed
implementation("io.swagger.core.v3:swagger-annotations")
implementation("io.swagger.core.v3:swagger-core")
// Jakarta namespace artifacts — no version needed
implementation("io.swagger.core.v3:swagger-annotations-jakarta")
implementation("io.swagger.core.v3:swagger-core-jakarta")
}