Understanding the @EndPoint Annotation

The @EndPoint annotation allows you to clearly describe your API endpoints directly in your Java code. It captures essential metadata about each endpoint, which ChazaAPI then uses to generate accurate and up-to-date API documentation automatically.

---

What Does @EndPoint Do?

By annotating your endpoint methods with @EndPoint, you provide key information such as:

• The group or category the endpoint belongs to.
• The HTTP method it supports (GET, POST, etc.).
• The URL path where the endpoint is accessible.
• The content type of the request or response.
• A concise description of what the endpoint does.
• Expected headers (like authentication tokens).
• Expected request fields (parameters or JSON payload).
• Expected response fields returned by the endpoint.
• The possible HTTP status codes and their meanings.
• The user roles authorized to access this endpoint.

---

Annotation Parameters Overview

Parameter	Type	Description	Default
group	String	Logical grouping or category of the endpoint (e.g., "auth", "user", "basic").	Required
method	Method enum	HTTP method the endpoint responds to (GET, POST, PUT, DELETE, PATCH).	Required
url	String	The URL path where this endpoint is accessible.	Required
description	String	A brief human-readable description of the endpoint’s purpose.	"" (empty)
request	RequestField[]	Array of expected request parameters or JSON fields, describing input data.	Empty array
response	ResponseField[]	Array of expected response fields, describing output data returned by the endpoint.	Empty array
headers	Header[]	HTTP headers expected by the endpoint (e.g., authentication tokens).	Empty array
statusCodes	StatusCode[]	HTTP status codes the endpoint may return, along with descriptions of each.	Empty array
contentType	String	Content-Type header value indicating the format of the request or response payload.	"application/json"
roles	String[]	User roles authorized to access this endpoint (e.g., "admin", "user").	{"any"}

---

Detailed Example

Here’s a practical example demonstrating how to use @EndPoint in a login API endpoint within a class annotated by @Chaza:

import annotations.*;
import io.javalin.http.Context;

@Chaza
public class GoodController2 {

    @EndPoint(
            group = "auth",
            method = Method.POST,
            url = "auth/login",
            contentType = "application/json",
            description = "an endpoint to login your stuff",
            headers = {
                    @Header(name = "Authorization", value = "Bearer token")
            },
            request = {
                    @RequestField(name = "username" , type = "string"),
                    @RequestField(name = "password" , type = "int")
            },
            response = {
                    @ResponseField(name = "status" , type = "boolean")
            },
            statusCodes = {
                    @StatusCode(code = 200, description = "OK"),
                    @StatusCode(code = 500, description = "Internal error"),
                    @StatusCode(code = 401 , description = "unauthorized")
            },
            roles = {"admin", "user"}
    )
    public static void login(Context ctx) {
        //login logic
        ctx.json("{}");
    }
}