# How to Configure Swagger/OpenAPI Documentation in the Mall Project

> Learn to configure Swagger OpenAPI documentation in the macrozheng mall project by extending BaseSwaggerConfig and customizing SwaggerProperties for each module.

- Repository: [macro/mall](https://github.com/macrozheng/mall)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Configure Swagger/OpenAPI documentation by extending `BaseSwaggerConfig` and returning a customized `SwaggerProperties` instance from the `swaggerProperties()` method in each module.**

The Mall project implements a centralized Swagger configuration architecture that standardizes API documentation across its microservices. To configure Swagger/OpenAPI documentation effectively, you extend the base configuration class and customize the properties for each specific module such as admin, portal, or search.

## Architecture Overview

The configuration relies on three core components that separate common functionality from module-specific settings.

### BaseSwaggerConfig

Located in [`mall-common/src/main/java/com/macro/mall/common/config/BaseSwaggerConfig.java`](https://github.com/macrozheng/mall/blob/main/mall-common/src/main/java/com/macro/mall/common/config/BaseSwaggerConfig.java), this abstract class provides the common `Docket` bean creation, security scheme configuration, and a critical `BeanPostProcessor` that fixes Springfox compatibility issues with Spring Boot 2.6+.

### SwaggerProperties

The `SwaggerProperties` POJO in [`mall-common/src/main/java/com/macro/mall/common/domain/SwaggerProperties.java`](https://github.com/macrozheng/mall/blob/main/mall-common/src/main/java/com/macro/mall/common/domain/SwaggerProperties.java) holds all configurable values including the base package, API metadata (title, description, version), contact information, and security flags.

### Module-Specific Configuration

Each module contains its own `SwaggerConfig` class (e.g., [`mall-admin/src/main/java/com/macro/mall/config/SwaggerConfig.java`](https://github.com/macrozheng/mall/blob/main/mall-admin/src/main/java/com/macro/mall/config/SwaggerConfig.java)) that extends `BaseSwaggerConfig` and provides concrete property values via the builder pattern.

## Configuration Flow

When the Spring application context initializes, the following sequence occurs:

1. Spring instantiates the module's `SwaggerConfig` bean annotated with `@Configuration` and `@EnableSwagger2`.
2. The configuration overrides `swaggerProperties()` to return a `SwaggerProperties` object built using the fluent builder API.
3. `BaseSwaggerConfig#createRestApi()` consumes these properties to construct a `Docket` bean:
   - **API scanning**: `RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage())` limits documentation generation to specific controller packages.
   - **Metadata**: Title, description, version, and contact details populate the `ApiInfo` object.
   - **Security**: When `enableSecurity` is `true`, an `Authorization` header `ApiKey` is added along with a `SecurityContext` matching `/*/.*` routes.
4. The `BeanPostProcessor` returned by `generateBeanPostProcessor()` removes Springfox's `PatternParser`-based handler mappings to ensure compatibility with newer Spring Boot versions.

## Customizing Swagger per Module

To adjust documentation for a specific service, create or modify the module's `SwaggerConfig` class:

```java
@Configuration
@EnableSwagger2
public class SwaggerConfig extends BaseSwaggerConfig {

    @Override
    public SwaggerProperties swaggerProperties() {
        return SwaggerProperties.builder()
                .apiBasePackage("com.macro.mall.admin.controller")
                .title("mall-admin 系统")
                .description("mall 后台管理系统接口文档")
                .contactName("macro")
                .contactUrl("https://github.com/macrozheng/mall")
                .contactEmail("macro@example.com")
                .version("1.0")
                .enableSecurity(true)
                .build();
    }

    @Bean
    public BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return generateBeanPostProcessor();
    }
}

```

### Key Configuration Properties

- **`apiBasePackage`**: Specifies the package to scan for `@RestController` and `@RequestMapping` annotations (e.g., `"com.macro.mall.portal.controller"`).
- **`title` / `description`**: Controls the header text and descriptive content displayed in the Swagger UI.
- **`contactName`, `contactUrl`, `contactEmail`**: Populates the contact section of the documentation.
- **`enableSecurity`**: When set to `true`, adds an **Authorize** button to the UI and includes the `Authorization` header in the OpenAPI spec.
- **`version`**: Displays the API version string at the top of the documentation interface.

## Dependencies and Compatibility

The project uses Springfox 3.0.0 declared in the parent [`pom.xml`](https://github.com/macrozheng/mall/blob/main/pom.xml):

```xml
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${springfox-swagger.version}</version>
</dependency>

```

Additional dependencies on `swagger-models` and `swagger-annotations` (v1.6.0) prevent `NumberFormatException` errors when running on Spring Boot 2.7+.

## Accessing the Documentation

After starting the Spring Boot application, access the Swagger UI at:

```text
http://localhost:{port}/swagger-ui/index.html

```

Replace `{port}` with your configured HTTP port (default 8080). The interface displays only controllers within the configured `apiBasePackage`.

For the raw OpenAPI specification, use:

```text
http://localhost:{port}/v2/api-docs

```

## Adding Swagger to a New Module

To implement Swagger documentation in a new module (e.g., `mall-payment`):

1. Ensure the module inherits the Springfox starter dependency from the parent POM.
2. Create a `SwaggerConfig` class extending `BaseSwaggerConfig` in the module's config package.
3. Override `swaggerProperties()` and set `apiBasePackage` to the module's controller package (e.g., `"com.macro.mall.payment.controller"`).
4. Include the `BeanPostProcessor` bean to maintain Spring Boot compatibility.
5. Verify the `@SpringBootApplication` scan path includes the configuration class.

## Configuring JWT Authorization

When `enableSecurity` is `true`, the generated OpenAPI specification includes:

```json
"securitySchemes": [
  {
    "type": "apiKey",
    "name": "Authorization",
    "in": "header"
  }
],
"security": [
  {
    "Authorization": []
  }
]

```

To authenticate requests in the Swagger UI:

1. Navigate to `http://localhost:8080/swagger-ui/index.html`.
2. Click the **Authorize** button in the top-right corner.
3. Enter the JWT token in the format: `Bearer eyJhbGci...`.
4. Click **Authorize** to apply the token to subsequent requests.

The actual JWT validation logic resides in [`mall-security/src/main/java/com/macro/mall/security/component/JwtAuthenticationTokenFilter.java`](https://github.com/macrozheng/mall/blob/main/mall-security/src/main/java/com/macro/mall/security/component/JwtAuthenticationTokenFilter.java).

## Summary

- **Extend `BaseSwaggerConfig`** in each module to inherit common Swagger setup and Spring Boot compatibility fixes.
- **Override `swaggerProperties()`** to return a `SwaggerProperties` builder instance with module-specific metadata, package scanning paths, and security settings.
- **Include the `BeanPostProcessor` bean** to prevent Springfox compatibility issues with Spring Boot 2.6 and later.
- **Set `enableSecurity`** to `true` for protected modules requiring JWT tokens, or `false` for public APIs.
- **Access the UI** at [`/swagger-ui/index.html`](https://github.com/macrozheng/mall/blob/main//swagger-ui/index.html) and the raw spec at `/v2/api-docs`.

## Frequently Asked Questions

### How do I enable or disable JWT authentication in Swagger UI?

Set the `enableSecurity` property in your `SwaggerProperties` builder to `true` (to show the Authorize button and require JWT tokens) or `false` (for public APIs that don't require authentication). When enabled, users must click **Authorize** in the Swagger UI and provide a Bearer token before testing endpoints.

### What is the purpose of the BeanPostProcessor in Swagger configuration?

The `BeanPostProcessor` returned by `generateBeanPostProcessor()` in `BaseSwaggerConfig` fixes a critical compatibility issue between Springfox and Spring Boot 2.6+ by removing handler mappings that rely on `PatternParser`. Without this processor, the Swagger UI fails to load on newer Spring Boot versions due to path pattern parsing changes.

### How do I change which controllers appear in the Swagger documentation?

Modify the `apiBasePackage` property in your module's `SwaggerConfig` to point to the specific package containing your controllers (e.g., `com.macro.mall.search.controller`). Only classes annotated with `@RestController` or `@RequestMapping` within this package and its subpackages will appear in the generated documentation.

### Where is the Swagger/OpenAPI JSON specification located?

The raw OpenAPI (Swagger 2.0) JSON is available at `http://localhost:{port}/v2/api-docs` when the application is running. This endpoint returns the complete API specification including all endpoints, parameters, and security schemes defined in your `SwaggerProperties` configuration.