APiGen Docs

Interactive API documentation module for APiGen, providing enhanced documentation experiences with Swagger UI, Redoc, and GraphQL Playground.

Features

• Enhanced Swagger UI - Try-it-now functionality with persistent authorization
• Redoc Integration - Beautiful, responsive three-panel documentation
• GraphQL Playground - Interactive IDE for GraphQL exploration
• Auto-generated Code Samples - Multi-language examples (curl, JavaScript, Python, Java, C#, Go, PHP, Ruby)
• API Versioning - Support for multiple API versions with deprecation notices

Installation

Add the dependency to your Spring Boot project:

Gradle:

dependencies {
    implementation 'com.jnzader.apigen:apigen-docs'
}

Maven:

<dependency>
    <groupId>com.jnzader.apigen</groupId>
    <artifactId>apigen-docs</artifactId>
</dependency>

Quick Start

The module auto-configures when added to your classpath. By default:

• Swagger UI: /swagger-ui
• Redoc: /redoc
• GraphQL Playground: /graphql-playground (requires apigen.docs.graphql-playground.enabled=true)
• Documentation Portal: /docs

Configuration

apigen:
  docs:
    enabled: true

    swagger-ui:
      enabled: true
      path: /swagger-ui
      try-it-enabled: true
      deep-linking: true
      display-request-duration: true
      persist-authorization: true
      syntax-highlight-theme: agate

    redoc:
      enabled: true
      path: /redoc
      expand-responses: all
      path-in-middle-panel: true
      required-props-first: true
      theme:
        primary-color: "#32329f"
        success-color: "#00aa13"
        warning-color: "#d4ac0d"
        error-color: "#e53935"

    graphql-playground:
      enabled: true
      path: /graphql-playground
      endpoint: /graphql
      editor-theme: dark
      tracing: false
      schema-polling: true
      schema-polling-interval: 2000

    code-samples:
      enabled: true
      languages:
        - curl
        - javascript
        - python
        - java
        - csharp
        - go
        - php
        - ruby
      default-language: curl
      include-auth: true

    versioning:
      enabled: false
      versions:
        - name: v1
          path: /v1
          default: true
          description: Current stable version
        - name: v2
          path: /v2
          description: Beta version with new features
          deprecation-notice: null

Features in Detail

Enhanced Swagger UI

The module enhances the default Swagger UI with:

• Try-it-now: Execute API calls directly from the documentation
• Persistent Authorization: JWT tokens are persisted across page reloads
• Deep Linking: Shareable URLs that point to specific operations
• Request Duration: Shows how long each request takes
• Syntax Highlighting: Configurable themes for code display

Redoc

Redoc provides an alternative documentation view with:

• Three-panel Design: Navigation, content, and code samples side-by-side
• Responsive Layout: Works on desktop and mobile
• Customizable Theme: Brand colors, fonts, and more
• Lazy Rendering: Fast loading even for large APIs

GraphQL Playground

For GraphQL APIs, the playground provides:

• Schema Explorer: Navigate your GraphQL schema visually
• Query Autocompletion: IntelliSense-like suggestions
• Query History: Access previously executed queries
• Subscription Support: Real-time WebSocket connections
• Tracing: Debug query performance

Auto-generated Code Samples

Code samples are automatically generated for each operation:

# curl
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"name": "John", "email": "[email protected]"}'

// JavaScript
const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({"name": "John", "email": "[email protected]"})
});

API Versioning

Support multiple API versions with:

• Version Selector: Switch between versions in the UI
• Deprecation Notices: Warn users about deprecated versions
• Per-version Specs: Different OpenAPI specs for each version

Documentation Portal

Access the documentation portal at /docs to see all available documentation formats:

• Direct links to Swagger UI, Redoc, and GraphQL Playground
• Version selector (when versioning is enabled)
• Download link for the raw OpenAPI specification

Customization

Custom CSS/JS

Inject custom CSS or JavaScript into Swagger UI:

apigen:
  docs:
    swagger-ui:
      custom-css-url: /static/custom-swagger.css
      custom-js-url: /static/custom-swagger.js

Custom Themes

Customize Redoc colors to match your brand:

apigen:
  docs:
    redoc:
      theme:
        primary-color: "#1976d2"
        font-family: "'Roboto', sans-serif"
        code-font-family: "'Fira Code', monospace"

Requirements

• Java 25+
• Spring Boot 4.0+
• SpringDoc OpenAPI 3.0.1+

License

MIT License - See LICENSE for details.