How to create Catwalk addons

🐾 Catwalk Addon Integration Guide (v0.8)

Step 1: Add JitPack Repository

To access the Catwalk library, include JitPack in your build configuration:

For Gradle:

repositories {
	maven { url 'https://jitpack.io' }
}

For Maven:

<repositories>
	<repository>
	    <id>jitpack.io</id>
	    <url>https://jitpack.io</url>
	</repository>
</repositories>

Step 2: Add the Dependency

Include the Catwalk dependency in your project.

For Gradle:

dependencies {
	implementation ("com.github.ikeepcalm:catwalk:v.0.8")
	compileOnly("io.javalin:javalin-bundle:6.6.0")
	compileOnly("io.javalin.community.openapi:javalin-openapi-plugin:6.6.0")
}

For Maven:

<dependencies>
    <!-- Catwalk dependency -->
    <dependency>
        <groupId>com.github.ikeepcalm</groupId>
        <artifactId>catwalk</artifactId>
        <version>v.0.8</version>
        <scope>compile</scope>
    </dependency>

    <!-- Javalin bundle -->
    <dependency>
        <groupId>io.javalin</groupId>
        <artifactId>javalin-bundle</artifactId>
        <version>6.6.0</version>
        <scope>provided</scope>
    </dependency>

    <!-- Javalin OpenAPI plugin -->
    <dependency>
        <groupId>io.javalin.community.openapi</groupId>
        <artifactId>javalin-openapi-plugin</artifactId>
        <version>6.6.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Step 3: Register your endpoint class

public class CatwalkAddon extends JavaPlugin {

    @Override
    public void onEnable() {
        CatWalkWebserverService webserverService = Bukkit.getServicesManager().load(CatWalkWebserverService.class);

        if (webserverService == null) {
            getLogger().severe("Failed to load CatWalkWebserverService from Bukkit ServicesManager.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        webserverService.registerHandlers(new YourEndpoint());
    }

}

Step 4: Implement your endpoints

public class YourEndpoint {

    @OpenApi(
            path = "/action",
            methods = HttpMethod.POST,
            description = "Calls for server action",
            tags = {"Actions"},
    )
    @BridgeEventHandler(description = "Initiates police teleport request", logRequests = true, scopes = {"police"})
    public BridgeApiResponse<TeleportResponse> endpointMethod(@BridgeRequestBody ActionRequest request) {
        // Actual implementation here
    }
}

• @BridgeEventHandler() marks your method as endpoint
• @OpenApi() allows to set path, HTTP methods, document response / request bodies, set description, etc.
• BridgeApiResponse<> is generic class for providing unified response:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    "id": 123,
    "name": "Example item",
    "details": {
      "createdAt": "2025-08-10T12:34:56Z",
      "tags": ["sample", "api", "response"]
    }
  }
}

Step 5: Define your @BridgeRequestBody object

It is basically DTO, which can be documented via annotations:

@JsonSchema
@JsonIgnoreProperties(ignoreUnknown = true)
@ApiSchema(
        description = "Action request",
        properties = {
                @ApiProperty(
                        name = "playerName",
                        type = "string",
                        description = "Name of the police officer to teleport",
                        required = true,
                        example = "ikeepcalm"
                ),
                @ApiProperty(
                        name = "action",
                        type = "string",
                        description = "Called action",
                        required = true,
                        example = "say hello {player}"
                )
        }
)
public class TeleportRequest {
    
    @JsonProperty("playerName")
    private String playerName;
    
    @JsonProperty("action")
    private String action;

}

Step 6: Compile, build, test

That's basically it.

In case you need more things like Path Params (e.g. /kill/{player}) you can use @BridgePathParam

In case you need more things like Query Params (e.g. /grant?amount=10}) you can use @BridgeQueryParam