Skip to content
Klutch.sh Docs

Deploying Ocular

Introduction

Ocular is an open-source API documentation viewer that transforms OpenAPI/Swagger specifications into beautiful, interactive documentation. It provides a clean, modern interface for exploring APIs, making it easy for developers to understand and test endpoints.

Built with a focus on developer experience, Ocular renders API documentation with syntax highlighting, interactive examples, and clear navigation. It supports multiple specification formats and can be customized to match your brand.

Key highlights of Ocular:

  • OpenAPI Support: Full support for OpenAPI 3.0 and Swagger 2.0
  • Interactive Examples: Try API endpoints directly from documentation
  • Clean Design: Modern, readable interface
  • Search Functionality: Quick navigation through endpoints
  • Syntax Highlighting: Code samples with proper formatting
  • Multiple Specs: Support for multiple API specifications
  • Customizable: Theme and branding options
  • Responsive: Works on desktop and mobile
  • Fast Loading: Optimized for performance
  • Open Source: MIT license with community support

This guide walks through deploying Ocular on Klutch.sh using Docker.

Why Deploy Ocular on Klutch.sh

Deploying Ocular on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the deployment automatically.

HTTPS by Default: Automatic SSL certificates for secure documentation access.

GitHub Integration: Version-controlled deployments through your repository.

Custom Domains: Use your own domain for professional documentation.

Scalable Resources: Allocate CPU and memory as needed.

Always-On Availability: Your API documentation remains accessible 24/7.

Prerequisites

Before deploying Ocular on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • An OpenAPI/Swagger specification file (JSON or YAML)
  • (Optional) A custom domain for your documentation

Understanding Ocular Architecture

Ocular has a simple architecture:

Static Site: Pre-rendered documentation for fast loading.

Specification Parser: Processes OpenAPI/Swagger files.

Interactive UI: JavaScript-powered interactive elements.

Theme Engine: Customizable styling and branding.

Deploying Ocular on Klutch.sh

    Create Your GitHub Repository

    Create a new GitHub repository for your documentation deployment.

    Add Your API Specification

    Add your OpenAPI specification to the repository:

    ocular-docs/
    ├── Dockerfile
    ├── openapi.yaml (or .json)
    └── config.yaml (optional)

    Create the Dockerfile

    Create a Dockerfile in your repository root:

    FROM node:18-alpine
    

    # Install serve for static file hosting
    RUN npm install -g serve
    

    # Create app directory
    WORKDIR /app
    

    # Install Redoc CLI for documentation generation
    RUN npm install -g @redocly/cli
    

    # Copy specification files
    COPY openapi.yaml ./
    

    # Generate static documentation
    RUN redocly build-docs openapi.yaml --output index.html
    

    EXPOSE 3000
    

    CMD ["serve", "-s", ".", "-l", "3000"]

    Alternative: Using Swagger UI

    For interactive testing capabilities:

    FROM swaggerapi/swagger-ui
    

    # Copy your spec
    COPY openapi.yaml /usr/share/nginx/html/
    

    # Configure Swagger UI to use your spec
    ENV SWAGGER_JSON=/usr/share/nginx/html/openapi.yaml
    ENV BASE_URL=/
    

    EXPOSE 8080

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project.

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 3000 (or 8080 for Swagger UI)

    Deploy Your Application

    Click Deploy to start the build process.

    Access Your Documentation

    Once deployed, access your API documentation at https://your-app.klutch.sh.

OpenAPI Specification

Basic Structure

Create a valid OpenAPI specification:

openapi: 3.0.3
info:
  title: My API
  description: API documentation
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Adding Examples

Include request/response examples:

paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              name: "John Doe"
              email: "john@example.com"
      responses:
        '201':
          description: User created
          content:
            application/json:
              example:
                id: 123
                name: "John Doe"

Authentication Documentation

Document auth requirements:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

Customization

Redoc Configuration

Customize Redoc appearance:

redocly.yaml
theme:
  colors:
    primary:
      main: "#1a73e8"
  typography:
    fontSize: "16px"
    fontFamily: "Inter, sans-serif"

Swagger UI Configuration

Customize Swagger UI:

ENV SWAGGER_JSON_URL=https://api.example.com/openapi.json
ENV VALIDATOR_URL=null
ENV DOM_ID=#swagger-ui
ENV DEEP_LINKING=true

Custom Branding

Add your logo and branding:

info:
  title: My API
  x-logo:
    url: "https://example.com/logo.png"
    altText: "My Company Logo"

Alternative Documentation Tools

Stoplight Elements

Modern API documentation:

FROM nginx:alpine
COPY openapi.yaml /usr/share/nginx/html/
COPY elements.html /usr/share/nginx/html/index.html

RapiDoc

Customizable API documentation:

FROM mrin9/rapidoc
COPY openapi.yaml /usr/share/nginx/html/
ENV SPEC_URL=/openapi.yaml

Production Best Practices

Specification Validation

Ensure valid specifications:

  1. Use OpenAPI linters
  2. Validate before deployment
  3. Test all examples
  4. Check schema references

Version Control

Manage documentation versions:

  1. Version your specifications
  2. Use semantic versioning
  3. Document breaking changes
  4. Maintain changelog

Performance

Optimize documentation loading:

  1. Minimize specification size
  2. Use CDN for static assets
  3. Enable caching
  4. Optimize images

Troubleshooting Common Issues

Specification Not Loading

  • Validate YAML/JSON syntax
  • Check file paths
  • Verify CORS settings
  • Review browser console

Missing Endpoints

  • Check path definitions
  • Verify schema references
  • Validate specification structure

Styling Issues

  • Check theme configuration
  • Verify CSS paths
  • Review build logs

Additional Resources

Conclusion

Deploying API documentation on Klutch.sh provides a professional, accessible way to share your API specifications. Whether using Redoc for clean documentation or Swagger UI for interactive testing, you can create comprehensive API documentation that helps developers integrate with your services effectively.