Skip to content

OpenAPI and Swagger

Unlike the .NET isolated worker, the Java worker has no first-class, Microsoft-supported OpenAPI extension that generates a spec from your @FunctionName annotations. The idiomatic approaches are: (1) let Azure API Management generate the OpenAPI definition when you import your HTTP endpoints, and (2) hand-author an openapi.json document and serve it — plus optionally a Swagger UI — from an HTTP function.

Architecture

flowchart TD
    FUNC[HTTP trigger functions] --> APIM[API Management import]
    APIM --> GEN[Generated OpenAPI definition]
    SPEC[Hand-authored openapi.json] --> SERVE[HTTP function serves /openapi.json]
    SERVE --> UI[Swagger UI page]

Option 1: Generate via API Management

Azure API Management can import your HTTP-triggered function endpoints and produce an OpenAPI definition. This works for function apps in any supported language, including Java. In the portal, open your function app, select API Management, create or link an instance, then Link API to import the endpoints and Download OpenAPI definition.

This is the lowest-effort path when you already front your functions with API Management.

Option 2: Serve a Hand-Authored Spec

Keep an openapi.json file on the classpath (for example under src/main/resources) and serve it from an HTTP function. This gives you a versioned, source-controlled contract without a code-generation dependency.

public class OpenApiFunction {

    @FunctionName("openapi")
    public HttpResponseMessage openapi(
        @HttpTrigger(
            name = "req",
            methods = {HttpMethod.GET},
            authLevel = AuthorizationLevel.ANONYMOUS,
            route = "openapi.json"
        ) HttpRequestMessage<Optional<String>> request
    ) throws IOException {
        String spec;
        try (InputStream in = getClass().getResourceAsStream("/openapi.json")) {
            spec = new String(in.readAllBytes(), StandardCharsets.UTF_8);
        }
        return request.createResponseBuilder(HttpStatus.OK)
            .header("Content-Type", "application/json")
            .body(spec)
            .build();
    }
}

Serve Swagger UI

Serve a minimal HTML page from another HTTP function that loads Swagger UI from a CDN and points it at the spec endpoint (/api/openapi.json). Store the HTML as a resource file and return it with Content-Type: text/html, mirroring the pattern above.

Keep the spec in sync

Because the spec is hand-authored, it can drift from your actual routes. Add a contract test that loads openapi.json and asserts every documented path has a matching @FunctionName route.

SpringDoc for Spring Cloud Function

If you run the Spring Cloud Function programming model instead of the plain annotation model, you can generate OpenAPI documentation with SpringDoc, the same way you would in a standard Spring Boot application.

See Also

Sources