All Projects → int128 → Gradle Swagger Generator Plugin

int128 / Gradle Swagger Generator Plugin

Licence: apache-2.0
Gradle plugin for OpenAPI YAML validation, code generation and API document publishing

Programming Languages

groovy
2714 projects

Projects that are alternatives of or similar to Gradle Swagger Generator Plugin

Drf Yasg
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.
Stars: ✭ 2,523 (+1180.71%)
Mutual labels:  swagger, openapi, swagger-ui
Django Ninja
💨 Fast, Async-ready, Openapi, type hints based framework for building APIs
Stars: ✭ 875 (+344.16%)
Mutual labels:  swagger, openapi, swagger-ui
Flasgger
Easy OpenAPI specs and Swagger UI for your Flask API
Stars: ✭ 2,825 (+1334.01%)
Mutual labels:  swagger, openapi, swagger-ui
Fastapi
FastAPI framework, high performance, easy to learn, fast to code, ready for production
Stars: ✭ 39,588 (+19995.43%)
Mutual labels:  swagger, openapi, swagger-ui
L5 Swagger
OpenApi or Swagger integration to Laravel
Stars: ✭ 1,781 (+804.06%)
Mutual labels:  swagger, openapi, swagger-ui
Rapipdf
PDF generation from OpenAPI / Swagger Spec
Stars: ✭ 132 (-32.99%)
Mutual labels:  swagger, openapi, swagger-ui
Swagger Ui
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Stars: ✭ 21,279 (+10701.52%)
Mutual labels:  swagger, openapi, swagger-ui
Springdoc Openapi
Library for OpenAPI 3 with spring-boot
Stars: ✭ 1,113 (+464.97%)
Mutual labels:  swagger, openapi, swagger-ui
Openapi Viewer
Browse and test a REST API described with the OpenAPI 3.0 Specification
Stars: ✭ 82 (-58.38%)
Mutual labels:  swagger, openapi, swagger-ui
Angular Swagger Ui
An angularJS implementation of Swagger UI
Stars: ✭ 131 (-33.5%)
Mutual labels:  swagger, openapi, swagger-ui
Express Oas Generator
OpenAPI (Swagger) specification generator for ExpressJS applications
Stars: ✭ 138 (-29.95%)
Mutual labels:  swagger, openapi, swagger-ui
Prism
Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.
Stars: ✭ 2,484 (+1160.91%)
Mutual labels:  swagger, openapi
Psswagger
The cmdlet generator from OpenAPI (f.k.a Swagger) specification
Stars: ✭ 160 (-18.78%)
Mutual labels:  swagger, openapi
Swagger meqa
Auto generate and run tests using swagger/OpenAPI spec, no coding needed
Stars: ✭ 151 (-23.35%)
Mutual labels:  swagger, openapi
Oooas
An object oriented approach to generating OpenAPI specs, implemented in PHP.
Stars: ✭ 162 (-17.77%)
Mutual labels:  swagger, openapi
Flama
🔥 Fire up your API with this flamethrower
Stars: ✭ 161 (-18.27%)
Mutual labels:  swagger, openapi
Swagger Node Codegen
An OpenAPI 3.x/Swagger 2 code generator for Node.js
Stars: ✭ 189 (-4.06%)
Mutual labels:  swagger, openapi
Openapi Client Axios
JavaScript client library for consuming OpenAPI-enabled APIs with axios
Stars: ✭ 168 (-14.72%)
Mutual labels:  swagger, openapi
Proteus
Lean, mean, and incredibly fast JVM framework for web and microservice development.
Stars: ✭ 178 (-9.64%)
Mutual labels:  swagger, openapi
Swagger to uml
Convert OpenAPI specifications (a.k.a. Swagger) to PlantUML diagrams
Stars: ✭ 144 (-26.9%)
Mutual labels:  swagger, openapi

Gradle Swagger Generator Plugin CircleCI Gradle Status

This is a Gradle plugin for the following tasks:

See also the following examples:

Code Generation

Create a project with the following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.18.2'
}

repositories {
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.2'             // Swagger Codegen V2
  swaggerCodegen 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.5'  // or Swagger Codegen V3
  swaggerCodegen 'org.openapitools:openapi-generator-cli:3.3.4'     // or OpenAPI Generator
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
    }
  }
}

The task generates source code into build/swagger-code-petstore.

% ./gradlew generateSwaggerCode
:resolveSwaggerTemplate NO-SOURCE
:generateSwaggerCodePetstore
:generateSwaggerCode NO-SOURCE

Document Generation

Swagger UI

Create a project with the following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.18.2'
}

repositories {
  jcenter()
}

dependencies {
  swaggerUI 'org.webjars:swagger-ui:3.10.0'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
  }
}

The task generates an API document as build/swagger-ui-petstore.

% ./gradlew generateSwaggerUI
:generateSwaggerUIPetstore
:generateSwaggerUI NO-SOURCE

ReDoc

Create a project with the following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.18.2'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
  }
}

The task generates an API document as build/redoc-petstore.

% ./gradlew generateReDoc
:generateReDocPetstore
:generateReDoc NO-SOURCE

HTML

Create a project with the following build script.

plugins {
  id 'org.hidetake.swagger.generator' version '2.18.2'
}

repositories {
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.2'             // Swagger Codegen V2
  swaggerCodegen 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.5'  // or Swagger Codegen V3
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'html'  // html or html2
    }
  }
}

The task generates a static HTML into build/swagger-code-petstore.

% ./gradlew generateSwaggerCode
:resolveSwaggerTemplate NO-SOURCE
:generateSwaggerCodePetstore
:generateSwaggerCode NO-SOURCE

Recipes

See the examples in acceptance-test.

Use configuration file

We can use a JSON configuration file as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
    }
  }
}

config.json depends on the language and framework. For example,

{
  "library": "spring-mvc",
  "modelPackage": "example.model",
  "apiPackage": "example.api",
  "invokerPackage": "example"
}

Run the task with Help postfix to show available JSON configuration.

% ./gradlew generateSwaggerCodePetstoreHelp
:generateSwaggerCodePetstoreHelp
=== Available raw options
NAME
        swagger-codegen-cli generate - Generate code with chosen lang

SYNOPSIS
        swagger-codegen-cli generate
                [(-a <authorization> | --auth <authorization>)]
...

=== Available JSON configuration for language spring:

CONFIG OPTIONS
	sortParamsByRequiredFlag
...

Build generated code

It is recommended to generate code into an ephemeral directory (e.g. build) and exclude it from a Git repository. We can compile generated code as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
    }
  }
}

// Configure compile task dependency and source
compileJava.dependsOn swaggerSources.petstore.code
sourceSets.main.java.srcDir "${swaggerSources.petstore.code.outputDir}/src/main/java"
sourceSets.main.resources.srcDir "${swaggerSources.petstore.code.outputDir}/src/main/resources"

See also the following examples:

Validate YAML before code generation

It is recommended to validate an OpenAPI YAML before code generation in order to avoid invalid code generated.

If you use OpenAPI Generator as generator, YAML validation is embeding.

We can validate a YAML as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
      // Validate YAML before code generation. for Swagger Codegen V2 / V3
      dependsOn validation
    }
  }
}

Selective generation

We can control output of code generation. At default everything is generated but only models and APIs are generated in the following:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      configFile = file('config.json')
      // Generate only models and controllers
      components = ['models', 'apis']
    }
  }
}

components property accepts a list of strings or map.

// generates only models
components = ['models']
components = [models: true]

// generate only User and Pet models
components = [models: ['User', 'Pet']]
components = [models: 'User,Pet']

// generate only APIs (without tests)
components = [apis: true, apiTests: false]
components = [apis: true, apiTests: null]

See selective generation section for details.

Use custom template

We can use a custom template for the code generation as follows:

// build.gradle
swaggerSources {
  inputFile = file('petstore.yaml')
  petstore {
    language = 'spring'
    // Path to the template directory
    templateDir = file('templates/spring-mvc')
  }
}

See also the following examples:

Use custom generator class

We can use a custom generator class for the code generation as follows:

// build.gradle
swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      // FQCN of the custom generator class
      language = 'CustomGenerator'
    }
  }
}

dependencies {
  swaggerCodegen project('generators')
}

swaggerSources*.code*.dependsOn 'generators:jar'
// generators/build.gradle (child project)
dependencies {
  implementation 'io.swagger:swagger-codegen-cli:2.4.2'
}
// generators/src/main/groovy/CustomGenerator.groovy
import io.swagger.codegen.languages.SpringCodegen

class CustomGenerator extends SpringCodegen {
}

See also the following examples:

Externalize template or generator class

In some large use case, we can release a template or generator to an external repository and use them from projects.

// build.gradle
repositories {
  // Use external repository for the template and the generator class
  maven {
    url 'https://example.com/nexus-or-artifactory'
  }
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.4.2'
  // Add dependency for the template
  swaggerTemplate 'com.example:swagger-templates:1.0.0'
  // Add dependency for the generator class
  swaggerCodegen 'com.example:swagger-generators:1.0.0'
}

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    code {
      language = 'spring'
      // The plugin automatically extracts template JAR into below destination
      templateDir = file("${resolveSwaggerTemplate.destinationDir}/spring-mvc")
    }
  }
}

See also the following examples:

Use multiple sources

We can handle multiple sources in a project as follows:

// build.gradle
swaggerSources {
    petstoreV1 {
        inputFile = file('v1-petstore.yaml')
        code {
            language = 'spring'
            configFile = file('v1-config.json')
        }
    }
    petstoreV2 {
        inputFile = file('v2-petstore.yaml')
        code {
            language = 'spring'
            configFile = file('v2-config.json')
        }
    }
}

compileJava.dependsOn swaggerSources.petstoreV1.code, swaggerSources.petstoreV2.code
sourceSets.main.java.srcDirs "${swaggerSources.petstoreV1.code.outputDir}/src/main/java", "${swaggerSources.petstoreV2.code.outputDir}/src/main/java"
sourceSets.main.resources.srcDirs "${swaggerSources.petstoreV1.code.outputDir}/src/main/resources", "${swaggerSources.petstoreV2.code.outputDir}/src/main/resources"

See also the following examples:

Switch version of Swagger Codegen

We can use multiple versions of Swagger Codegen as follows:

// build.gradle
configurations {
    swaggerCodegenV2
    swaggerCodegenV3
}

dependencies {
    swaggerCodegenV2 'io.swagger:swagger-codegen-cli:2.4.2'
    swaggerCodegenV3 'io.swagger.codegen.v3:swagger-codegen-cli:3.0.5'
}

swaggerSources {
    petstoreV2 {
        inputFile = file('v2-petstore.yaml')
        code {
            language = 'spring'
            configuration = configurations.swaggerCodegenV2
        }
    }
    petstoreV3 {
        inputFile = file('v3-petstore.yaml')
        code {
            language = 'spring'
            configuration = configurations.swaggerCodegenV3
        }
    }
}

See also the following examples:

Configure Swagger UI

We can configure Swagger UI by overwriting the default index.html as follows:

swaggerSources {
  petstore {
    inputFile = file('petstore.yaml')
    ui {
      doLast {
        copy {
          from 'index.html'
          into outputDir
        }
      }
    }
  }
}

You can create an index.html from the Swagger UI official one. It must satisfy the followings:

  • Put <script src="./swagger-spec.js"> in order to load a Swagger spec. The plugin exports the Swagger spec as swagger-spec.js file while generation.
  • Set spec: window.swaggerSpec in SwaggerUIBundle() parameters.
  • Set validatorUrl: null in SwaggerUIBundle() parameters in order to turn off the validator badge.

See also the following examples:

Settings

The plugin adds validateSwagger, generateSwaggerCode, generateSwaggerUI and GenerateReDoc tasks. A task will be skipped if no input file is given.

Task type ValidateSwagger

The task accepts below properties.

Key Type Value Default value
inputFile File Swagger spec file. Mandatory
reportFile File File to write validation report. $buildDir/tmp/validateSwagger/report.yaml

It depends on the following JSON schema:

Task type GenerateSwaggerCode

The task accepts below properties.

Key Type Value Default value
language String Language to generate. Mandatory
inputFile File Swagger spec file. Mandatory
outputDir File Directory to write generated files. $buildDir/swagger-code
wipeOutputDir Boolean Wipe the outputDir before generation. true
library String Library type. None
configFile File JSON configuration file. None
templateDir File Directory containing the template. None
components List or Map Components to generate that is a list of models, apis and supportingFiles. All components
additionalProperties Map of String, String Additional properties. None
rawOptions List of Strings Raw command line options for Swagger Codegen None
configuration String or Configuration Configuration for Swagger Codegen configurations.swaggerCodegen

Task type GenerateSwaggerUI

The task accepts below properties.

Key Type Value Default value
inputFile File Swagger spec file. Mandatory
outputDir File Directory to write Swagger UI files. $buildDir/swagger-ui
wipeOutputDir Boolean Wipe the outputDir before generation. true

Note that options and header are no longer supported since 2.10.0. See the Migration Guide for details.

Task type GenerateReDoc

The task accepts below properties.

Key Type Value Default value
inputFile File Swagger spec file. Mandatory
outputDir File Directory to write ReDoc files. $buildDir/swagger-redoc
wipeOutputDir Boolean Wipe the outputDir before generation. true
scriptSrc String URL to ReDoc JavaScript. //rebilly.github.io/ReDoc/releases/latest/redoc.min.js
title String HTML title. ReDoc - $filename
options Map of Strings ReDoc tag attributes. Empty map

Contributions

This is an open source software licensed under the Apache License Version 2.0. Feel free to open issues or pull requests.

CircleCI builds the plugin continuously. Following variables should be set.

Environment Variable Purpose
$GRADLE_PUBLISH_KEY Publish the plugin to Gradle Plugins
$GRADLE_PUBLISH_SECRET Publish the plugin to Gradle Plugins
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].