_resource.json

Path: apis/<api>/resources/<resource>/_resource.json

Holds the IDE-specific metadata for a resource that isn't in the OpenAPI spec: creation defaults, notes, spec overrides, extra parameters, locally-defined operations, and plugin data. Operation details (schemas, responses) stay in the spec; this file only stores what you add on top.

Example

{
  "version": 1,
  "defaults": {
    "headers": { "Accept": "application/json" }
  },
  "overrides": {
    "description": "Everything about your pets."
  },
  "operations": {
    "create": {
      "defaults": { "body": { "status": "available" } },
      "notes": "Requires the write:pets scope.",
      "overrides": {
        "summary": "Add a new pet to the store",
        "responses": { "405": { "description": "Invalid input" } }
      },
      "parameters": {
        "X-Trace-Id": { "in": "header", "schema": { "type": "string" }, "description": "Tracing id" }
      }
    }
  }
}

Fields

operations.<name>

Overrides

Overrides are projected onto the effective spec. At the operation level the overridable fields are summary, description, tags, deprecated, security, externalDocs, responses.<code>, requestBody, and x-* extensions. Identity fields (method, path, operationId) are not overridable; change those through schema rules.

Parameters

The parameters dictionary is keyed by parameter name. Each entry is merged into the effective spec's parameter list by identity (name + in). Setting an entry to nullremoves that parameter from the effective spec.

Locally-defined operations

The define block lets you add an operation the source spec doesn't have, useful for undocumented endpoints or APIs without a spec. The organizational part (which resource, what name) is created with craftr schema define; the full definition lives here:

"operations": {
  "vaccinations": {
    "define": { "method": "GET", "path": "/pet/{petId}/vaccinations", "operationId": "getPetVaccinations" },
    "overrides": { "summary": "List a pet's vaccinations" },
    "parameters": { "petId": { "in": "path", "required": true, "schema": { "type": "integer" } } }
  }
}