OpenAPI

📘 OpenAPI + RapiDoc UI Integration

MicroFox supports automatic OpenAPI 3.1 documentation generation with a beautiful and interactive RapiDoc UI out of the box — no Spring, no config files.

Just add a single dependency and annotate your endpoints using standard Swagger (OpenAPI) annotations. MicroFox takes care of the rest.

⚙️ Enabling OpenAPI

To enable OpenAPI support in MicroFox, add the following Maven dependency:

<dependency>
    <groupId>ir.moke.microfox</groupId>
    <artifactId>microfox-openapi</artifactId>
    <version>${microfox.version}</version>
</dependency>

This automatically enables:

• An OpenAPI JSON spec at:

/docs/openapi.json

• An interactive RapiDoc panel at:

/docs

📄 RapiDoc Web Panel

The /docs endpoint opens a lightweight RapiDoc interface that consumes the /openapi JSON spec and renders a modern, filterable, and interactive API UI.

You can explore your endpoints, test APIs, and inspect schemas directly from the browser.

🧪 Example: Annotating an Endpoint

Here’s how you can document a REST endpoint using Swagger annotations:

@Operation(
    summary = "Add new client",
    tags = "client",
    operationId = "add",
    requestBody = @RequestBody(
        description = "Client DTO",
        required = true,
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = Client.class)
        )
    ),
    responses = {
        @ApiResponse(
            description = "Successfully operation",
            responseCode = "200",
            content = @Content(
                mediaType = "application/json",
                array = @ArraySchema(schema = @Schema(implementation = Client.class))
            )
        ),
        @ApiResponse(description = "Invalid Input", responseCode = "400"),
        @ApiResponse(description = "Internal Server Error", responseCode = "500")
    }
)

🧱 Example DTO Schema

You can also annotate your POJOs to define their schema representation in the OpenAPI spec:

@Schema(name = "client", description = "Example client object")
public class Client {
    @Schema(description = "Unique client ID", example = "1")
    private int id;

    @Schema(description = "Client first name", example = "Mahdi")
    private String name;

    @Schema(description = "Client last name", example = "Sheikh Hosseini")
    private String family;

    // Constructors, Getters, Setters...
}

📚 Supported Annotations

Annotation	Usage
@Operation	Describes the API operation (summary, tags, responses)
@RequestBody	Documents the body of HTTP POST/PUT requests
@ApiResponse	Defines expected responses (status codes, content)
@Schema	Describes the structure and metadata of models (DTOs)
@Parameter	Describes query/path/header parameters

These annotations are part of io.swagger.v3.oas.annotations.

📦 Under the Hood

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core-jakarta</artifactId>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-models-jakarta</artifactId>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations-jakarta</artifactId>
</dependency>

It generates the spec at runtime using static servlet metadata, without scanning annotations via reflection at startup.

✅ Benefits

• Minimal setup – Just add the dependency
• Live API docs – /docs with auto-refresh from /openapi
• OpenAPI 3.1 compatible
• No extra config or YAML needed
• Supports standard Swagger annotations
• UI powered by RapiDoc