OpenAPI Specification (OAS) API Documentation Sync

Overview

This guide will help you set up the OpenAPI Specification (OAS) integration with Brainfish to import your API documentation and make it available for AI-powered assistance. The integration allows you to upload OpenAPI/Swagger specification files and automatically generate detailed usage scenarios for each API endpoint.

Prerequisites

Before you begin, ensure you have:

1. OpenAPI Specification File: A valid OpenAPI 3.0 or Swagger 2.0 specification file (JSON or YAML format)
2. Brainfish Account: A Brainfish account with appropriate permissions
3. File Access: The ability to upload files to your Brainfish workspace
4. API Documentation: Well-documented API endpoints with summaries and descriptions

Step 1: Prepare Your OpenAPI Specification File

1. Validate Your OAS File

1. Check File Format
   • Ensure your file is in JSON or YAML format
   • Supported extensions: .json, .yaml, .yml
   • Maximum file size: 50MB
2. Verify OAS Version
   • OpenAPI 3.0.x (recommended)
   • Swagger 2.0 (supported)
   • Check the openapi or swagger field in your specification
3. Review API Documentation
   • Ensure each endpoint has a summary field
   • Add detailed description fields where possible
   • Include request/response examples for better AI context

2. Optimize Your Specification

1. Add Meaningful Summaries

   /users/{id}:
     get:
       summary: "Retrieve user information by ID"
       description: "Fetches detailed user information including profile data, preferences, and account status"
   

2. Include Request Examples

   /users:
     post:
       summary: "Create a new user"
       requestBody:
         content:
           application/json:
             example:
               name: "John Doe"
               email: "john@example.com"
   

3. Document Response Schemas

   responses:
     200:
       description: "User created successfully"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/User"
   

Step 2: Set Up Integration in Brainfish

1. Access Knowledge Section

1. Log into Brainfish
   • Go to your Brainfish dashboard
   • Navigate to the "Knowledge" section in the left sidebar
2. Create New Source
   • Click "Add Source" or "New Source"
   • This opens the source configuration dialog

2. Select OpenAPI Specification

1. Choose Source Type
   • In the source type selector, choose "OpenAPI Specification"
   • You'll see the OAS configuration panel

3. Upload Your Specification File

1. Select File
   • Click "Choose File" or drag and drop your OAS file
   • Supported formats: .json, .yaml, .yml
   • Maximum size: 50MB
2. File Validation
   • The system will automatically validate your file format
   • Ensure the file contains valid OpenAPI/Swagger specification
   • Check for any validation errors in the interface
3. Upload Process
   • The file will be uploaded to secure cloud storage
   • You'll see a progress indicator during upload
   • Wait for the upload to complete before proceeding

4. Configure Sync Settings

1. Enable Daily Sync (Recommended)
   • Toggle "Enable daily sync" to automatically keep your API documentation up-to-date
   • This will re-process your OAS file daily at 2:00 AM UTC
2. Save Configuration
   • Click "Save" to create your OAS integration
   • The system will begin processing your specification file

Step 3: Monitor Processing and Verification

1. Initial Processing

1. Background Processing
   • After saving, the system processes your OAS file in the background
   • This may take several minutes depending on the number of endpoints
   • You can monitor progress in the Knowledge section
2. AI Context Generation
   • For each API endpoint, the system generates detailed usage scenarios
   • This includes user/system context, goals, parameters, expected behavior, and examples
   • The AI analyzes your specification to create realistic documentation

2. Verify Content Import

1. Check Imported Endpoints
   • Once processing is complete, your API endpoints will appear in Brainfish
   • Each endpoint will have generated documentation and usage scenarios
   • You can search for specific endpoints or API functionality
2. Review Generated Content
   • Navigate to the Knowledge section to see your imported API documentation
   • Each endpoint will include:
     • Original API path and method
     • Generated usage scenarios
     • Parameter descriptions
     • Request/response examples

Step 4: Enable for AI Agents

1. Configure Agent Access

1. Access Agent Settings
   • Go to the "Agents" section in Brainfish
   • Select the agent you want to enable for API documentation
2. Enable OAS Source
   • In the agent's knowledge sources, enable your OAS integration
   • This allows the agent to reference your API documentation when answering questions

2. Test AI Integration

1. Ask API Questions
   • Use the chat interface to ask questions about your API
   • Example questions:
     • "How do I create a new user?"
     • "What parameters are required for the authentication endpoint?"
     • "Show me an example of the user update request"
2. Verify Responses
   • The AI should provide detailed, contextual answers based on your API specification
   • Responses should include code examples and usage scenarios

Troubleshooting

Common Issues

1. "Invalid OAS File Format" Error

Possible Causes:

• File is not a valid OpenAPI/Swagger specification
• Incorrect file format (not JSON or YAML)
• Malformed JSON or YAML syntax

Solutions:

• Validate your OAS file using online tools like Swagger Editor
• Check for syntax errors in your JSON or YAML
• Ensure the file contains openapi or swagger field

2. "File Size Exceeds Limit" Error

Possible Causes:

• OAS file is larger than 50MB
• File contains excessive examples or documentation

Solutions:

• Remove unnecessary examples or detailed descriptions
• Split large APIs into multiple specification files
• Use references to external files for large schemas

3. "No Endpoints Found" Error

Possible Causes:

• OAS file doesn't contain any paths
• All endpoints are missing required fields
• File structure is incorrect

Solutions:

• Ensure your OAS file has a paths section with endpoint definitions
• Add summary fields to all endpoints
• Verify the file structure follows OpenAPI specification

4. "Processing Failed" Error

Possible Causes:

• Large number of endpoints causing timeout
• Network connectivity issues
• AI service temporarily unavailable

Solutions:

• The system will automatically retry processing
• For large APIs, processing may take longer
• Check system status and try again later

5. "AI Context Generation Failed" Error

Possible Causes:

• Endpoints lack sufficient documentation
• AI service rate limits
• Complex endpoint structures

Solutions:

• Add more detailed descriptions to your endpoints
• Include request/response examples
• The system will fall back to basic endpoint information

File Requirements

Your OAS file must meet these requirements:

• Format: JSON or YAML
• Size: Maximum 50MB
• Version: OpenAPI 3.0.x or Swagger 2.0
• Structure: Must contain valid paths section
• Content: At least one endpoint with summary field

Processing Limitations

The OAS integration has the following limitations:

• File Size: Maximum 50MB per file
• Endpoints: No limit on number of endpoints
• Processing Time: Varies based on file size and endpoint count
• AI Context: Generated for each endpoint with sufficient documentation

Best Practices

1. API Documentation Quality

• Write clear summaries: Each endpoint should have a descriptive summary
• Include examples: Add request/response examples for better AI understanding
• Document parameters: Provide detailed parameter descriptions
• Use consistent naming: Follow consistent naming conventions across your API

2. File Organization

• Keep files focused: Split large APIs into domain-specific files
• Use references: Reference external schema files to reduce file size
• Version control: Keep your OAS files in version control
• Regular updates: Update your specification when APIs change

3. Integration Management

• Monitor sync status: Check sync status regularly in the Knowledge section
• Update specifications: Upload new versions when APIs are updated
• Test AI responses: Regularly test AI responses to ensure accuracy
• Review generated content: Verify that generated usage scenarios are accurate

4. Security Considerations

• Remove sensitive data: Ensure your OAS file doesn't contain API keys or secrets
• Use examples carefully: Avoid including real user data in examples
• Review before upload: Double-check your specification before uploading

Advanced Configuration

1. Custom AI Prompts

The system uses AI to generate detailed usage scenarios for each endpoint. The generated content includes:

• User/System Context: Who or what is using the API
• Goal: What the user aims to achieve
• Data/Parameters: Required information and parameters
• Expected Behavior: How the endpoint should behave
• Business Value: Benefits provided by the endpoint
• Payload Examples: Sample request payloads

2. Sync Scheduling

• Daily Sync: Automatically processes your OAS file daily at 2:00 AM UTC
• Manual Sync: Trigger manual sync from the Knowledge section
• Real-time Updates: Upload new versions anytime to update content

3. Content Management

• Automatic Updates: New endpoints are automatically added
• Removed Endpoints: Endpoints removed from the specification are automatically removed from Brainfish
• Content Versioning: Previous versions are maintained for reference

Support and Resources

Getting Help

If you encounter issues with the OAS integration:

1. Check Documentation: Review this guide for common solutions
2. Validate Your File: Use Swagger Editor to validate your OAS file
3. Contact Support: Reach out to the Brainfish support team

Useful Resources

• OpenAPI Specification: https://spec.openapis.org/
• Swagger Editor: https://editor.swagger.io/
• OpenAPI Examples: https://github.com/OAI/OpenAPI-Specification/tree/master/examples

Contact Information

For technical support or questions about the OAS integration:

• Email: support@brainfi.sh
• Documentation: https://docs.brainfi.sh
• Status Page: https://status.brainfi.sh