Swagger OpenAPI for Hero Beans - VittorioDeMarzi/hero-beans GitHub Wiki

Description

This page explains how we wired springdoc-openapi (Swagger UI) in the project, how to add tags, configure JWT bearer auth for the “Authorize” button and how to use the UI day-to-day.

Live documentation. Annotations in controllers automatically generate a Swagger-UI page with all endpoints, their parameters, models, and examples.
Quick testing. You can send requests directly from the browser (no need for Postman): add a token, request body, and see the response.
Onboarding and support. New developers don’t need to dig into the code — the whole API is visible right away.
Clear security. It shows where bearerAuth is required.

1. Dependency

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6")

After adding it, Swagger UI is available out-of-the-box at:

UI: http://localhost:8080/swagger-ui.html

2. OpenAPI config (JWT bearer + metadata)

techcourse.herobeans.configuration.OpenApiConfig:

package techcourse.herobeans.configuration

import io.swagger.v3.oas.models.Components
import io.swagger.v3.oas.models.OpenAPI
import io.swagger.v3.oas.models.info.Info
import io.swagger.v3.oas.models.security.SecurityScheme
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class OpenApiConfig {

    @Bean
    fun openAPI(): OpenAPI {
        val bearer = SecurityScheme()
            .type(SecurityScheme.Type.HTTP)
            .scheme("bearer")
            .bearerFormat("JWT")

        return OpenAPI()
            .info(
                Info()
                    .title("Hero Beans API")
                    .version("v1")
                    .description("Coffee shop backend — products, cart, addresses, auth, and admin ops.")
            )
            .components(Components().addSecuritySchemes("bearerAuth", bearer))
    }
}

This defines the bearerAuth scheme so the UI shows an Authorize button

3. Tagging controllers & documenting operations

import io.swagger.v3.oas.annotations.tags.Tag
import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.security.SecurityRequirement
import io.swagger.v3.oas.annotations.Parameter

@Tag(name = "Cart", description = "Member cart operations")
@SecurityRequirement(name = "bearerAuth")  // lock icon; sends JWT automatically
@RestController
@RequestMapping("/api/member/cart")
class CartController(/*...*/) {

    @Operation(summary = "Get current cart")
    @GetMapping
    fun getCartItems(
         @LoginMember member: MemberDto
    ): ResponseEntity<CartProductResponse> { /*...*/ }

    @Operation(summary = "Add option to cart (increments if exists)")
    @PostMapping("/{id}")
    fun addProduct(
        @Parameter(hidden = true) @LoginMember member: MemberDto,
        @PathVariable("id") optionId: Long
    ): ResponseEntity<MessageResponseDto> { /*...*/ }
}

Notes

@Tag sets the group name/description in UI.
@Operation(summary = "...") adds a neat one-liner under each operation.
Add @SecurityRequirement(name = "bearerAuth") to any secured controller/method.

4. Using Swagger UI (how-to)

Open the UI
Call POST /api/members/register or POST /api/members/login. Copy the token from response.
Click Authorize paste the token only (no Bearer prefix) → Authorize.