Configuring the Swagger codegen with Gradle. How does the provided Gradle script work?

Question

I am doing battle with this code here: https://github.com/thebignet/swagger-codegen-gradle-plugin-example

Trying to build a REST client using Swagger codegen and Gradle. I am new to Gradle and looking at this example is quite confusing as there are multiple variables / properties / names that I have no clue where they come from or what they do. Especially this part:

clean.doFirst {
    delete(swaggerOutputDir)
}

configurations {
    swagger
}

sourceSets {
    swagger {
        compileClasspath = configurations.swaggerCompile
        java {
            srcDir file("${project.buildDir.path}/swagger/src/main/java")
        }
    }
    main {
        compileClasspath += swagger.output
        runtimeClasspath += swagger.output
    }
    test {
        compileClasspath += swagger.output
        runtimeClasspath += swagger.output
    }
}

compileSwaggerJava.dependsOn generateApi
classes.dependsOn swaggerClasses
compileJava.dependsOn compileSwaggerJava

swagger.output - where this comes from?

classes, compileJava, swaggerClasses, compileSwaggerJava What are all of those? They don't seem to be defined anywhere and seem to be randomly named?

Then the readme says: In order to generate Swagger source code, launch the following task. generateApi : generate Swagger code

Where the hell are Swagger and code coming from?

Any clarifications are much appreciated and I believe will help a lot more people.

Answer 1

To fully understand this code, you have to read through the Gradle DSL (domain-specific-language)

• A SourceSet:

A SourceSet represents a logical group of Java source and resources.

Inside the block sourceSets{ }, a new SourceSet swagger is defined.

In the above link to the SourceSet's definition, you will notice that since swagger is now a SourceSet, it has the property 'output' which provides all the output directories of this SourceSet: thus, you can call swagger.output

In every Gradle Java project, there is the assumption there are main sources and test sources. This assumption is introduced by the java plugin, which is required for Gradle to process Java. (This standardized layout stems from the Standard Directory Layout.) You configure those source sets through main{} and test{}. Of course, you may have more source sets.
What compileClasspath += swagger.output and runtimeClasspath += swagger.output does, is add the swagger-generated code (or any swagger output in general) in their compile-time and runtime classpath directory. Since swagger does code generation, this is expected behavior.

• Now, about Gradle Tasks:

A Task represents a single atomic piece of work for a build, such as compiling classes or generating javadoc.

The java plugin mentioned above, when creating a new SourceSet, creates also some associated tasks: compileSourceSetJava, processSourceSetResources and sourceSetClasses (replacing SourceSet with each SourceSet's name). That's what those compileSwaggerJava, swaggerClasses are, the generated tasks from the swagger SourceSet.
For the standard sourcesets, those tasks are:
main sourceset's tasks: compileJava, processResources, classes
test sourceset's tasks: compileTestJava, processTestResources, testClasses

A task may have dependencies on other tasks or might be scheduled to always run after another task.

This is configured through the task's properties. One of those, is the dependsOn property which explains this last block of your provided code. (Note: the generateApi task in the last block of code, is defined in the link the OP shared in the question)