gRPC OpenAPI Documentation¶

Last Updated: 2025-11-23

This document explains how to view and use the auto-generated OpenAPI specifications for ocmonica's gRPC services.

Overview¶

Ocmonica's gRPC services are documented using OpenAPI v2 (Swagger) specifications, auto-generated from protobuf definitions. These specs provide a machine-readable description of the gRPC API that can be viewed in various OpenAPI tools.

Key Benefits: - Machine-readable API documentation - Compatible with Swagger UI, Postman, Insomnia - Auto-generated from protobuf (always in sync) - Schema validation and examples - Can generate client SDKs

Generated Files¶

The OpenAPI specifications are generated in docs/grpc/ (gitignored) and include:

Service Specifications¶

file_service.swagger.json - File operations
Upload, download, list, delete files
File metadata management
Move and copy operations
directory_service.swagger.json - Directory operations
Create, list, delete directories
Directory metadata
Move operations
search_service.swagger.json - Search functionality
File and directory search
Server streaming search
group_service.swagger.json - Group management
Create, update, delete groups
Member management
Group listing
watched_folder_service.swagger.json - Watched folders
Create and manage watched folders
Trigger scans
List indexed files
playback_position_service.swagger.json - Media playback
Track video/audio playback positions
Resume playback
settings_service.swagger.json - User settings
Manage user preferences
Application settings
filesystem_service.swagger.json - Filesystem operations
Low-level filesystem access
common.swagger.json - Shared types
Common message definitions
Shared enums and types

Generating Documentation¶

Generate OpenAPI Specs¶

# Generate all OpenAPI specifications
task grpc:docs

# Or directly with buf
buf generate

This command: 1. Reads protobuf definitions from proto/ 2. Generates OpenAPI v2 (Swagger) specs 3. Outputs to docs/grpc/ocmonica/v1/

Clean Generated Docs¶

# Remove generated OpenAPI files
rm -rf docs/grpc/

Note: Generated files are gitignored and should not be committed. They are regenerated on demand.

Viewing OpenAPI Specs¶

Option 1: Swagger Editor (Online)¶

Quick and easy for one-off viewing:

Visit Swagger Editor
Click File → Import File
Select a spec file (e.g., docs/grpc/ocmonica/v1/file_service.swagger.json)
View the interactive API documentation

Pros: - No installation required - Interactive documentation - Live schema validation - Try-it-out functionality

Cons: - Requires uploading file to external service - Not suitable for sensitive projects

Option 2: Swagger UI (Docker)¶

For local, private viewing:

# Start Swagger UI on port 8081
docker run -p 8081:8080 \
  -v $(pwd)/docs/grpc:/usr/share/nginx/html/specs \
  -e SWAGGER_JSON=/specs/ocmonica/v1/file_service.swagger.json \
  swaggerapi/swagger-ui

# Open http://localhost:8081

View multiple specs:

Create a simple index HTML:

<!DOCTYPE html>
<html>
<head>
  <title>Ocmonica gRPC API Docs</title>
</head>
<body>
  <h1>Ocmonica gRPC Services</h1>
  <ul>
    <li><a href="?url=/specs/ocmonica/v1/file_service.swagger.json">File Service</a></li>
    <li><a href="?url=/specs/ocmonica/v1/directory_service.swagger.json">Directory Service</a></li>
    <li><a href="?url=/specs/ocmonica/v1/search_service.swagger.json">Search Service</a></li>
    <li><a href="?url=/specs/ocmonica/v1/group_service.swagger.json">Group Service</a></li>
    <li><a href="?url=/specs/ocmonica/v1/watched_folder_service.swagger.json">Watched Folder Service</a></li>
  </ul>
</body>
</html>

Option 3: Postman¶

For API testing and exploration:

Open Postman
Click Import
Select File tab
Upload spec file (e.g., file_service.swagger.json)
Postman creates a collection with all endpoints

Features: - Pre-configured requests - Environment variables - Request history - Collection sharing

Option 4: VS Code Extension¶

For viewing within your editor:

Install Swagger Viewer extension
Open a .swagger.json file
Press Shift+Alt+P (or Cmd+Shift+P on Mac)
Select Preview Swagger

Understanding the Specs¶

OpenAPI v2 Format¶

Generated specs follow OpenAPI 2.0 (Swagger) format:

{
  "swagger": "2.0",
  "info": {
    "title": "ocmonica/v1/file_service.proto",
    "version": "version not set"
  },
  "paths": {
    "/ocmonica.v1.FileService/UploadFile": {
      "post": {
        "summary": "UploadFile uploads a new file",
        "operationId": "FileService_UploadFile",
        "parameters": [...],
        "responses": {...}
      }
    }
  },
  "definitions": {...}
}

Key Sections¶

paths: All available RPC methods - Each gRPC method becomes a POST endpoint - Path format: /package.service/Method

definitions: Message types and schemas - Protobuf messages → JSON schemas - Request and response types - Nested message definitions

parameters: Request parameters - Request message fields - Query parameters - Headers

responses: Response schemas - Success responses (200) - Error responses - Response message schemas

Use Cases¶

1. API Exploration¶

Discover available endpoints and their parameters:

# View all available services
ls docs/grpc/ocmonica/v1/*.swagger.json

# Open in Swagger Editor to explore interactively

2. Client SDK Generation¶

Generate client libraries from OpenAPI specs:

# Generate TypeScript client (example)
npx @openapitools/openapi-generator-cli generate \
  -i docs/grpc/ocmonica/v1/file_service.swagger.json \
  -g typescript-fetch \
  -o generated/typescript-client

# Generate Python client (example)
openapi-generator-cli generate \
  -i docs/grpc/ocmonica/v1/file_service.swagger.json \
  -g python \
  -o generated/python-client

Note: Using ConnectRPC's native client generation (buf generate) is recommended over OpenAPI-generated clients for better type safety and streaming support.

3. Contract Testing¶

Use specs to validate API behavior:

// Example: Validate response against schema
import { validateResponse } from 'openapi-validator';

const spec = require('./docs/grpc/ocmonica/v1/file_service.swagger.json');
const response = await fetch('/ocmonica.v1.FileService/ListFiles');

const validation = validateResponse(spec, response);
if (!validation.valid) {
  console.error('Response does not match schema:', validation.errors);
}

4. Documentation Integration¶

Embed in documentation sites:

<!-- ReDoc example -->
<redoc spec-url='./file_service.swagger.json'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>

Comparison: OpenAPI vs Protobuf¶

When to Use OpenAPI Specs¶

Use OpenAPI specs when: - Exploring APIs in Swagger UI/Postman - Generating documentation for non-technical users - Generating client SDKs for languages without protobuf support - Contract testing and validation - Integrating with OpenAPI-based tools

When to Use Protobuf¶

Use protobuf definitions when: - Generating native gRPC/ConnectRPC clients (recommended) - Type-safe development (compile-time checking) - Streaming RPC support - Server-side development - Better performance (binary encoding)

Recommendation: Use protobuf as the source of truth. OpenAPI specs are generated from protobuf and serve as a supplementary documentation/integration format.

Limitations¶

Known Limitations of OpenAPI Generation¶

Streaming Not Supported
OpenAPI v2 doesn't support streaming RPCs
SearchStream appears as a regular POST endpoint
Use native gRPC/ConnectRPC clients for streaming
Version Not Set
OpenAPI specs show "version": "version not set"
Can be customized via protobuf options (future enhancement)
No Authentication Details
Specs don't include JWT authentication info
Must manually add security definitions if needed
Binary Data
Binary file uploads/downloads shown as base64 strings
Not ideal for large files

Workarounds¶

For streaming support: Use native ConnectRPC clients (see grpc.md)

For version info: Add protobuf options:

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "File Service API";
    version: "1.0";
  };
};

For authentication: Manually add security definitions to specs (or use Swagger UI configuration)

Configuration¶

buf.gen.yaml¶

OpenAPI generation is configured in buf.gen.yaml:

plugins:
  # OpenAPI v2 (Swagger) documentation generation
  - remote: buf.build/grpc-ecosystem/openapiv2:v2.25.1
    out: docs/grpc
    opt:
      - json_names_for_fields=true
      - generate_unbound_methods=true

Options: - json_names_for_fields=true: Use JSON field names (not protobuf names) - generate_unbound_methods=true: Include all methods (not just HTTP-annotated)

Customization¶

Add protobuf options for better OpenAPI output:

import "protoc-gen-openapiv2/options/annotations.proto";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Ocmonica File Service";
    version: "1.0.0";
    contact: {
      name: "Ocmonica Team";
      url: "https://github.com/j-pye/ocmonica";
    };
  };
  schemes: HTTPS;
  consumes: "application/json";
  produces: "application/json";
  security_definitions: {
    security: {
      key: "BearerAuth";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "Authorization";
      }
    }
  };
};