OpenAPI Integration¶

The BerryCrush plugin integrates with OpenAPI specifications to provide intelligent code assistance for API operations.

Overview¶

When you reference an API operation with ^operationId, the plugin: - Validates the operation exists - Provides autocomplete for operation IDs - Shows operation details on hover - Navigates to the OpenAPI definition

OpenAPI File Detection¶

The plugin uses content-based detection to find OpenAPI specification files.

Detection Method¶

The plugin scans all .yaml, .yml, and .json files in the project and checks their content for OpenAPI markers:

Marker	Version
`openapi: 3.x`	OpenAPI 3.x (YAML)
`swagger: 2.x`	Swagger/OpenAPI 2.x (YAML)
`"openapi": "3.x"`	OpenAPI 3.x (JSON)
`"swagger": "2.x"`	Swagger/OpenAPI 2.x (JSON)

Example Detection¶

A file is recognized as an OpenAPI spec if it contains:

YAML format:

openapi: 3.1.0
info:
  title: My API

JSON format:

{
  "openapi": "3.0.0",
  "info": { "title": "My API" }
}

Filename Hints¶

Files with these patterns are checked first (optimization): - Filenames containing openapi or swagger - api.yaml, api.yml, api.json

Referencing Operations¶

Use the ^ prefix to reference an OpenAPI operation:

scenario: Create a user
  when I create a new user
    call ^createUser
      body: {"name": "John"}
    assert status 201

The ^createUser references the operation with operationId: createUser in your OpenAPI spec.

Autocompletion¶

Operation IDs¶

Type ^ and press Ctrl+Space:

call ^    # Shows: createUser, getUser, deleteUser, ...

Parameters¶

After selecting an operation, get parameter suggestions:

call ^getUser
  #    Shows: userId, ...

Response Codes¶

For assertions:

assert status     # Shows: 200, 201, 400, 404, ...

Hover Information¶

Hover over ^operationId to see:

Operation summary
HTTP method and path
Parameters (path, query, header, body)
Response codes
Description

Example tooltip:

getUser
GET /users/{userId}

Parameters:
- userId (path, required): The user ID

Responses:
- 200: User found
- 404: User not found

Go to Definition¶

Hold Ctrl / Cmd and click on ^operationId
Opens the OpenAPI file at the operation definition

Find Usages¶

Place cursor on operation ID in OpenAPI file
Press Alt+F7
See all scenarios using this operation

Multiple OpenAPI Files¶

Per-Scenario Configuration¶

Associate specific OpenAPI files with scenarios:

# openapi: ./api/users.openapi.yaml
scenario: User Management
  ...

Project-Wide Configuration¶

In .berrycrush.yaml or project settings:

openapi:
  - path: src/main/resources/openapi/main-api.yaml
    prefix: api
  - path: src/test/resources/mock-api.yaml
    prefix: mock

Validation¶

Missing Operation Warning¶

If an operation doesn't exist in any OpenAPI file:

call ^nonExistent    # Warning: Unknown operation 'nonExistent'

Parameter Validation¶

The plugin validates required parameters:

call ^getUser    # Warning: Missing required path parameter 'userId'

OpenAPI Versions¶

Supported versions:

Version	Support
OpenAPI 3.1	Full
OpenAPI 3.0	Full
Swagger 2.0	Partial

Schema Support¶

Request Body Completion¶

For operations with a request body:

call ^createUser
  body:       # Shows fields from User schema
    name: "value"
    email: "value"

Response Assertions¶

Use JSONPath to assert response fields:

assert $.name equals "John"    # Validated against response schema

Troubleshooting¶

Operations Not Found¶

Verify OpenAPI file is in a recognized location
Check file follows naming conventions
Ensure operationId is defined for each operation
Invalidate caches and restart IDE

Autocomplete Not Working¶

Ensure OpenAPI file is valid (no syntax errors)
Check file is indexed
Verify plugin is enabled
Look for parsing errors in Event Log

Wrong OpenAPI File Used¶

Check file proximity rules
Use explicit # openapi: directive
Configure project-level settings

Schema Parsing Errors¶

Validate OpenAPI file with external tool
Check for circular references
Ensure all $ref references are valid

Best Practices¶

Operation Naming¶

Use descriptive, consistent operation IDs:

# Good
operationId: createUser
operationId: getUserById
operationId: updateUserEmail

# Avoid
operationId: create
operationId: user
operationId: postUserUpdate

Organization¶

project/
├── src/
│   ├── main/
│   │   └── resources/
│   │       └── openapi/
│   │           ├── api.openapi.yaml
│   │           └── schemas/
│   │               └── user.yaml
│   └── test/
│       └── resources/
│           └── scenarios/
│               └── user-tests.scenario

Version Control¶

Keep OpenAPI files in version control alongside scenarios: - Scenarios reference operations that exist - Changes to API require scenario updates - CI can verify consistency

Advanced Features¶

Schema Inheritance¶

The plugin understands allOf, oneOf, and anyOf for autocomplete:

User:
  allOf:
    - $ref: '#/components/schemas/Person'
    - type: object
      properties:
        role:
          type: string

External References¶

Supports $ref to external files:

$ref: './schemas/user.yaml#/components/schemas/User'

Discriminators¶

For polymorphic schemas, autocomplete shows all variants.