Create API Endpoint

def "should return projects for API v44"() {
    when:
    def response = client.get("/api/44/projects")
    
    then:
    response.status == 200
    response.json.size() > 0
}

def "should reject for API v43"() {
    when:
    def response = client.get("/api/43/projects")
    
    then:
    response.status == 404 // or appropriate error
}

@Schema(description = "Project response")
class ProjectResponse {
    
    @Schema(description = "Project name", example = "MyProject")
    String name
    
    @Schema(description = "Project description")
    String description
    
    @Schema(description = "Creation date", example = "2025-01-01T00:00:00Z")
    String created
}

@Controller(value = "/api/44")
class ProjectController {
    // ...
}

@Operation(
    method = "GET",
    summary = "List Projects",
    description = "Returns a list of all projects accessible to the user"
)
@Tag(name = "Project")
@ApiResponse(
    responseCode = "200",
    description = "Project list successfully retrieved",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = ProjectListResponse.class)
    )
)
@Get(uri = "/projects", produces = MediaType.APPLICATION_JSON)
def listProjects() {
    // implementation
}

@Operation(
    method = "POST",
    summary = "Create Project",
    description = "Creates a new project with the specified configuration",
    requestBody = @RequestBody(
        description = "Project configuration",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = ProjectCreateRequest.class)
        ),
        required = true
    )
)
@ApiResponse(
    responseCode = "201",
    description = "Project created successfully",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = ProjectResponse.class)
    )
)
@Post(uri = "/projects")
def createProject() {
    // implementation
}

@Parameters([
    @Parameter(
        name = "project",
        in = ParameterIn.PATH,
        description = "Project name",
        required = true,
        schema = @Schema(type = "string")
    ),
    @Parameter(
        name = "includeArchived",
        in = ParameterIn.QUERY,
        description = "Include archived items",
        schema = @Schema(type = "boolean", defaultValue = "false")
    )
])
@Get(uri = "/project/{project}/jobs")
def getProjectJobs() {
    // implementation
}

// Add dependencies using versions centralized in gradle.properties
compileOnly "io.micronaut.openapi:micronaut-openapi:${micronautOpenapiVersion}"
implementation "io.swagger.core.v3:swagger-annotations:${swaggerVersion}"

// Set target file
tasks.withType(GroovyCompile) {
    def target = new File(
        project.rootDir, 
        "rundeckapp/build/openapi/${project.name}.yml"
    ).absolutePath
    configure(groovyOptions) {
        forkOptions.jvmArgs = [
            '-Xmx1024m',
            "-Dmicronaut.openapi.target.file=${target}".toString()
        ]
    }
}

# API tests
./gradlew :functional-test:apiTest

# Verify OpenAPI spec generated
ls rundeckapp/build/classes/groovy/main/META-INF/swagger/rundeck-*.yml

# Full test suite
./gradlew test

@Controller(value = "/api/44/base-path")  // Required

@Get|@Post|@Put|@Delete(uri = "/path")    // Required - HTTP method
@Operation(...)                             // Required - OpenAPI operation
@Tag(name = "Category")                     // Required - Grouping (or tags=["Category"] in @Operation)
@ApiResponse(...)                           // Required - Response definition
@Parameters([...])                          // Optional - Query/path params

@Schema(...)                                // Required on DTO classes