Spring Boot OpenAPI: නියම API Documentation හදමු! (Beyond Swagger UI)

කොහොමද යාලුවනේ! අද අපි කතා කරන්නේ අපේ Software Development Project වලට අත්‍යවශ්‍යම දෙයක් ගැන – ඒ තමයි API Documentation. විශේෂයෙන්ම, අපි Spring Boot වලින් හදන RESTful APIs වලට documentation හදනකොට බොහෝ වෙලාවට අපිට මතක් වෙන්නේ Swagger UI ගැන විතරයි නේද? ඒත් ඇත්තටම, OpenAPI Specification (OAS) කියන්නේ ඊට එහා ගිය ලෝකයක්. අද අපි බලමු කොහොමද ඒ ලෝකේ customize කරලා, අපේ API documentation එකට නියම Professional look එකක් දෙන්නේ කියලා, ඒ වගේම අපේ Project එකට ගැලපෙන්න ඒක හරියට හදාගන්නේ කොහොමද කියලත්.

බොහෝ විට, developers ලා කරන්නේ Springdoc-OpenAPI වගේ library එකක් add කරලා, default Swagger UI එක එහෙම්මම තියන එක. ඒක වැරදි නැහැ, හැබැයි පොඩි customizing ටිකකින් අපිට පුළුවන් අපේ API docs එක users ලාට, නැත්නම් වෙන developers ලාට තවත් පහසුවෙන් තේරුම් ගන්න පුදන්න. API එකක් කියන්නේ අපේ system එකේ interface එකනේ. ඒක කොච්චර හොඳට document කරනවද කියන එක මත තමයි අනිත් අය ඒක use කරන විදිහ තීරණය වෙන්නේ.

1. OpenAPI කියන්නේ මොකක්ද? (Swagger ට වඩා වෙනස්!)

ගොඩක් අය "OpenAPI" කියන නම ඇහුනම "Swagger" කියලා හිතනවා. ඒක සම්පූර්ණයෙන්ම වැරදි නැහැ, හැබැයි පොඩි වෙනසක් තියනවා. OpenAPI Specification (OAS) කියන්නේ RESTful APIs describe කරන්න හදපු standard එකක්, file format එකක් (JSON or YAML). ඒක හරියට blueprint එකක් වගේ. මේ blueprint එකට අනුව අපේ API එකේ endpoints මොනවද, ඒවට යවන data මොනවද, එන data මොනවද, මොන error code එකට මොන response එකද එන්නේ වගේ හැම දෙයක්ම specify කරන්න පුළුවන්.

Swagger කියන්නේ මේ OpenAPI Specification එකට අදාළව tools set එකක්. ඒකේ ප්‍රධාන ඒවා ටිකක් මෙන්න:

• Swagger UI: මේක තමයි අපිට browser එකෙන් පේන interactive documentation tool එක. OpenAPI spec එක read කරලා ලස්සනට UI එකක් හදලා දෙනවා.
• Swagger Codegen: මේකෙන් පුළුවන් OpenAPI spec එකෙන් Client Libraries, Server Stubs වගේ දේවල් generate කරන්න.
• Swagger Editor: මේකෙන් පුළුවන් OpenAPI spec files හදන්නයි, edit කරන්නයි.

ඉතින් තේරෙනවනේ, OpenAPI කියන්නේ specification එක. Swagger කියන්නේ ඒ specification එකත් එක්ක වැඩ කරන්න පුළුවන් tools ටිකක්. අපි Spring Boot එක්ක වැඩ කරනකොට සාමාන්‍යයෙන් Springdoc-OpenAPI වගේ libraries පාවිච්චි කරන්නේ මේ OpenAPI specification එකට අනුකූලව API documentation automate කරන්න. මේ libraries, අපේ code එක analyze කරලා OpenAPI spec එක generate කරනවා, ඊට පස්සේ ඒක Swagger UI එකට දීලා අපිට ලස්සන UI එකක් පෙන්නනවා.

2. Spring Boot වල OpenAPI Add කරමු (පොඩි Setup එකක්)

Spring Boot project එකකට OpenAPI support එක add කරන එක ඉතාම පහසුයි. Springdoc-OpenAPI කියන්නේ මේකට තියන ජනප්‍රියම library එක. ඔයාගේ pom.xml file එකට මේ dependency එක එකතු කරන්න:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version> <!-- නවතම version එක බලලා දාන්න -->
</dependency>

ඔයා webflux පාවිච්චි කරනවා නම්, springdoc-openapi-starter-webflux-ui කියන එක use කරන්න. Dependency එක add කරලා project එක run කරාම, සාමාන්‍යයෙන් ඔයාට http://localhost:8080/swagger-ui.html කියන URL එකෙන් ඔයාගේ API documentation එක බලන්න පුළුවන්. ඒකෙන් ඔයාගේ project එකේ තියන controllers, endpoints ඔක්කොම automatically detect කරලා පෙන්නයි. මේක තමයි default behavior එක. දැන් අපි බලමු මේක Customize කරන්නේ කොහොමද කියලා.

3. API Documentation එක Customize කරමු! (වඩාත් Professional විදියට)

මෙන්න මේ section එක තමයි වැදගත්ම දේ. අපි බලමු කොහොමද අපේ API documentation එකට අපිට ඕන විදියට නමක්, විස්තරයක්, contact details, security info වගේ දේවල් add කරන්නේ කියලා.

3.1. පොදු තොරතුරු (API Info) Add කරමු

ඔයාගේ API එක ගැන පොදු තොරතුරු (Title, Description, Version, Contact Info, License) add කරන්න පුළුවන් application.properties නැත්නම් application.yml file එකේ මේ විදිහට:

# application.properties

springdoc.info.title=My Awesome Product API
springdoc.info.description=API for managing products, users, and orders.
springdoc.info.version=1.0.0
springdoc.info.terms-of-service=http://example.com/terms/
springdoc.info.contact.name=SC Team
springdoc.info.contact.url=http://srilankancodeguide.com
[email protected]
springdoc.info.license.name=Apache 2.0
springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0.html

# For external documentation links
springdoc.external-docs.description=Find more about our APIs here
springdoc.external-docs.url=http://example.com/external-docs

මේවා add කරාම ඔයාගේ Swagger UI එකේ උඩින්ම මේ තොරතුරු ටික ලස්සනට පෙන්වයි. මේකෙන් ඔයාගේ API එක ගැන පොඩි overview එකක් ගන්න එන අයට ලොකු පහසුවක් වෙනවා. ඒ වගේම, මේකෙන් අපේ documentation එකට professional look එකක් ලැබෙනවා.

3.2. API Operations Customize කරමු (Annotations පාවිච්චි කරලා)

අපි හදන Controller methods වලට උඩින් දාන annotations වලින් අපිට පුළුවන් තව විස්තර එකතු කරන්න. මේවා තමයි වැදගත්ම දේවල්:

• @Operation: API operation එකක් ගැන summary එකක්, description එකක් දෙන්න.
• @Parameter: Path variables, Query parameters, Header parameters වගේ දේවල් describe කරන්න.
• @RequestBody: Request body එක ගැන විස්තර (description, required/optional, examples) දෙන්න.
• @ApiResponse: විවිධ HTTP response codes (200 OK, 400 Bad Request, 500 Internal Server Error) වලට එන response එක ගැන විස්තර කරන්න.
• @Tag: Operations Group කරන්න.

මෙන්න පොඩි code example එකක්:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.Collections;
import java.util.List;

@RestController
@RequestMapping("/api/products")
@Tag(name = "Product Management", description = "Operations related to product management")
public class ProductController {

    @Operation(summary = "Get all products", description = "Retrieve a list of all available products.",
            tags = {"Product Browsing"})
    @ApiResponse(responseCode = "200", description = "Successfully retrieved list of products",
            content = @Content(mediaType = "application/json",
                    schema = @Schema(implementation = Product.class, type = "array")))
    @ApiResponse(responseCode = "500", description = "Internal server error")
    @GetMapping
    public ResponseEntity<List<Product>> getAllProducts() {
        // ... implementation
        return ResponseEntity.ok(Collections.emptyList());
    }

    @Operation(summary = "Create a new product", description = "Add a new product to the inventory.",
            requestBody = @RequestBody(description = "Product object to be created", required = true,
                    content = @Content(mediaType = "application/json",
                            schema = @Schema(implementation = Product.class),
                            examples = @ExampleObject(name = "Example Product Request",
                                    value = "{\"id\":101, \"name\":\"Sample Product\", \"price\":19.99}"))))
    @ApiResponse(responseCode = "201", description = "Product created successfully",
            content = @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)))
    @ApiResponse(responseCode = "400", description = "Invalid product details supplied")
    @ApiResponse(responseCode = "409", description = "Product with given ID already exists")
    @PostMapping
    public ResponseEntity<Product> createProduct(@RequestBody Product product) {
        // ... implementation
        return ResponseEntity.status(201).body(product);
    }

    @Operation(summary = "Get product by ID", description = "Retrieve a single product by its unique ID.")
    @Parameter(name = "productId", description = "ID of the product to retrieve", required = true, example = "1")
    @ApiResponse(responseCode = "200", description = "Product found",
            content = @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)))
    @ApiResponse(responseCode = "404", description = "Product not found")
    @GetMapping("/{productId}")
    public ResponseEntity<Product> getProductById(@PathVariable Long productId) {
        // ... implementation
        return ResponseEntity.notFound().build();
    }
}

// Dummy Product class for demonstration
class Product {
    private Long id;
    private String name;
    private double price;

    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public double getPrice() { return price; }
    public void setPrice(double price) { this.price = price; }
}

මේ annotations පාවිච්චි කරලා ඔයාගේ API documentation එකට අවශ්‍ය හැම විස්තරයක්ම add කරන්න පුළුවන්. @ExampleObject එකෙන් පුළුවන් Request body වලට අදාළ JSON examples add කරන්න. ඒක Developers ලාට Request එකක් හදනකොට ලොකු පහසුවක්.

3.3. Security Configuration එකතු කරමු

ඔයාගේ API එකට authentication (API Key, OAuth2, JWT Bearer Token) තියනවා නම්, ඒකත් documentation එකේ mention කරන්න පුළුවන්. මේකට @SecurityScheme සහ @SecurityRequirement කියන annotations පාවිච්චි කරනවා. සාමාන්‍යයෙන් මේවා Configuration class එකක define කරනවා:

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
        info = @Info(title = "My Product API", version = "1.0.0"),
        security = @SecurityRequirement(name = "bearerAuth") // This applies to all operations unless overridden
)
@SecurityScheme(
        name = "bearerAuth",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer",
        description = "Provide a valid JWT token in the Authorization header. E.g., 'Bearer <token>'
)
public class OpenAPIConfig {
    // No beans needed here if only using annotations
}

උඩ තියන විදිහට @SecurityScheme එකෙන් අපේ security mechanism එක define කරනවා. @OpenAPIDefinition එකේ security attribute එකෙන් පුළුවන් මුළු API එකටම මේ security requirement එක apply කරන්න. සමහර operations වලට විතරක් security ඕනිනම්, @SecurityRequirement annotation එක ඒ particular method එකට උඩින් දාන්න පුළුවන්.

3.4. API Grouping (විශාල Project වලට වැදගත්)

ඔයාගේ Project එකේ APIs ගොඩක් තියනවා නම්, ඒවා Groups වලට බෙදලා පෙන්නන එක හොඳයි. උදාහරණයක් විදියට, "Admin APIs" සහ "Public APIs" කියලා groups දෙකක් හදන්න පුළුවන්. මේක කරන්න පුළුවන් application.properties එකෙන් හෝ Java Configuration වලින්.

Java Configuration (@GroupedOpenApi Bean):

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupsConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-apis") // Group name
                .pathsToMatch("/api/**") // Regex to include paths
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin-apis")
                .pathsToMatch("/admin/**") // Regex to include paths
                .build();
    }
}

මේ විදිහට Groups හැදුවාම, Swagger UI එකේ dropdown එකකින් මේ Groups අතර මාරු වෙන්න පුළුවන්. ඒකෙන් documentation එක organize කරලා, user friendly කරන්න පුළුවන්.

4. ප්‍රයෝගික උපදෙස් (වැදගත් Tips ටිකක්)

මතක තියාගන්න ඕනේ පොඩි පොඩි දේවල් ටිකක් මෙන්න:

1. Documentation එක Up-to-Date තියන්න: API එක modify කරනකොට අනිවාර්යයෙන්ම documentation එකත් update කරන්න. නැත්නම් ඒක වැරදි තොරතුරු දෙන, වැඩක් නැති දෙයක් වෙනවා.
2. Clear Descriptions පාවිච්චි කරන්න: @Operation, @Parameter වගේ annotations වලට දෙන descriptions පැහැදිලි වෙන්න ඕනේ. හරියටම මොකක්ද මේ operation එක කරන්නේ, parameters වලින් මොනවද බලාපොරොත්තු වෙන්නේ කියලා තේරෙන්න ඕනේ.
3. Examples Add කරන්න: Request bodies, Response bodies වලට @ExampleObject පාවිච්චි කරලා examples දාන එක හුඟක් වටිනවා. Developers ලාට ඉක්මනටම Request එකක් හදාගන්න පුළුවන් වෙනවා.
4. API Versioning ගැන හිතන්න: ඔයාගේ API එකේ versions තියනවා නම් (/v1/products, /v2/products වගේ), documentation එකත් ඒ අනුව organize කරන්න. Grouping මේකට හොඳ විසඳුමක්.
5. CI/CD එකට Integrate කරන්න: Documentation generation process එක ඔයාගේ Continuous Integration / Continuous Deployment pipeline එකට integrate කරන්න. ඒකෙන් manual errors අඩු වෙනවා, documentation එක හැමදාම latest version එකට අදාළව තියනවා.
6. Model Classes වලටත් Comments දාන්න: ඔයාගේ DTO (Data Transfer Object) නැත්නම් model classes වල attributes වලට උඩින් comments දාන්න. Springdoc-OpenAPI මේවා analyze කරලා Swagger UI එකේ Schema Model එකේ describe කරනවා.

මේ පොඩි පොඩි දේවල් වලින් ඔයාගේ API documentation එකේ quality එක ගොඩක් වැඩි කරගන්න පුළුවන්. ඒක ඔයාගේ Team එකට විතරක් නෙවෙයි, ඔයාගේ API එක use කරන අනිත් developers ලාටත් ලොකු පහසුවක් වේවි. හිතන්න, අලුතින් කෙනෙක් Project එකට ආවම, ඔයාගේ documentation එක බලලා ඉක්මනටම API එක ගැන තේරුම් ගන්න පුළුවන් නම් කොච්චර වටිනවද!

අවසාන වශයෙන් (Let's wrap it up!)

අද අපි Spring Boot එක්ක OpenAPI පාවිච්චි කරලා අපේ API documentation එක customize කරන්නේ කොහොමද කියලා කතා කළා. Swagger UI එකේ default look එකෙන් එහා ගිහින්, අපිට අවශ්‍ය විදියට Title, Description, Contact Info, Security Details, Grouping, සහ individual Operation details පවා add කරන්න පුළුවන් බව අපි දැක්කා. මේ customization වලින් ඔයාගේ API එක වඩාත් Professional විදියට document කරන්න පුළුවන්, ඒ වගේම ඒක use කරන අයට ලොකු පහසුවක් වෙනවා. මතක තියාගන්න, හොඳ API එකක් කියන්නේ හොඳ code එකක් වගේම, හොඳ documentation එකක් කියන එකත් අත්‍යවශ්‍යයි.

ඉතින්, දැන් ඔයාලත් මේ දේවල් ඔයාලගේ Project වලට try කරලා බලන්න. මොකද හිතෙන්නේ? ඔයාලා දැනටමත් මේ වගේ customization කරලා තියනවද? එහෙම නැත්නම් මේ ලිපියෙන් ඉගෙන ගත්තු අලුත් දේවල් මොනවද? ඔයාලගේ අදහස්, ප්‍රශ්න පහළින් comment කරන්න. හැමෝටම ජය වේවා!