configuration-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Configuration",
  "description": "Configuration defines code generation customizations.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "package": {
      "type": "string",
      "description": "PackageName to generate the code under."
    },
    "copyright-header": {
      "type": "string",
      "description": "CopyrightHeader is the header to add to the generated code. Use without //."
    },
    "skip-prune": {
      "type": "boolean",
      "description": "SkipPrune indicates whether to skip pruning unused components on the generated code."
    },
    "output": {
      "$ref": "#/definitions/Output",
      "description": "Output specifies the output options for the generated code."
    },
    "generate": {
      "$ref": "#/definitions/GenerateOptions",
      "description": "Generate options for the generated code."
    },
    "filter": {
      "$ref": "#/definitions/FilterConfig",
      "description": "Filter is the configuration for filtering the paths and operations to be parsed."
    },
    "overlay": {
      "$ref": "#/definitions/OverlayOptions",
      "description": "Overlay specifies OpenAPI Overlay files to apply to the spec before generation."
    },
    "additional-imports": {
      "type": "array",
      "description": "AdditionalImports defines any additional Go imports to add to the generated code.",
      "items": {
        "$ref": "#/definitions/AdditionalImport"
      }
    },
    "error-mapping": {
      "type": "object",
      "description": "ErrorMapping is the configuration for mapping the OpenAPI error responses to Go types. The key is the generated error type name and the value is the dotted json path to the string result.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "client": {
      "type": "object",
      "description": "Client defines options for the generated client.",
      "$ref": "#/definitions/Client"
    },
    "user-templates": {
      "type": "object",
      "description": "UserTemplates is the map of user-provided templates overriding the default ones.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "user-context": {
      "type": "object",
      "description": "UserContext is the map of user-provided context values to be used in templates user overrides.",
      "additionalProperties": true
    }
  },
  "required": [],
  "definitions": {
    "Output": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "use-single-file": {
          "type": "boolean",
          "description": "Whether to generate the output into a single file."
        },
        "directory": {
          "type": "string",
          "description": "Directory where generated files should be placed."
        },
        "filename": {
          "type": "string",
          "description": "Filename to use if single file output is enabled."
        }
      },
      "required": []
    },
    "GenerateOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "client": {
          "type": "boolean",
          "description": "Client specifies whether to generate a client. Defaults to false."
        },
        "models": {
          "type": "boolean",
          "description": "Models specifies whether to generate model types. Defaults to true. Set to false when models are generated in a separate package."
        },
        "handler": {
          "$ref": "#/definitions/HandlerOptions",
          "description": "Handler specifies options for handler/server code generation. If not specified, no handler code is generated."
        },
        "mcp-server": {
          "$ref": "#/definitions/MCPServerOptions",
          "description": "MCPServer specifies options for MCP (Model Context Protocol) server generation. If set, generates MCP tools that wrap the generated client for AI assistant integration. Requires client generation to be enabled."
        },
        "omit-description": {
          "type": "boolean",
          "description": "OmitDescription specifies whether to omit schema description from the spec in the generated code. Defaults to false."
        },
        "default-int-type": {
          "type": "string",
          "description": "DefaultIntType specifies the default integer type to use in the generated code. Can be 'int', 'int32', or 'int64'. Defaults to 'int'."
        },
        "always-prefix-enum-values": {
            "type": "boolean",
            "description": "AlwaysPrefixEnumValues specifies whether to always prefix enum values with the schema name. Defaults to true."
        },
        "validation": {
          "$ref": "#/definitions/ValidationOptions",
          "description": "Validation specifies options for Validate() method generation."
        }
      },
      "required": []
    },
    "FilterConfig": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "include": {
          "$ref": "#/definitions/FilterParamsConfig",
          "description": "Paths, tags, operation IDs, and schema properties to include."
        },
        "exclude": {
          "$ref": "#/definitions/FilterParamsConfig",
          "description": "Paths, tags, operation IDs, and schema properties to exclude."
        }
      },
      "required": []
    },
    "FilterParamsConfig": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of paths to include or exclude."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of tags to include or exclude."
        },
        "operation-ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of operation IDs to include or exclude."
        },
        "schema-properties": {
          "type": "object",
          "description": "Mapping of schema names to property names to include or exclude.",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "extensions": {
          "type": "array",
          "description": "List of extension names to include or exclude",
          "items": {
            "type": "string"
          }
        }
      },
      "required": []
    },
    "OverlayOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "Specifies OpenAPI Overlay files to apply to the spec before generation. See https://spec.openapis.org/overlay/v1.0.0.html",
      "properties": {
        "sources": {
          "type": "array",
          "description": "List of overlay files to apply to the OpenAPI spec. Each source can be a file path or URL. Overlays are applied in order.",
          "items": {
            "type": "string"
          }
        }
      },
      "required": []
    },
    "AdditionalImport": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "alias": {
          "type": "string",
          "description": "Optional alias for the import."
        },
        "package": {
          "type": "string",
          "description": "Package path to import."
        }
      },
      "required": [
        "package"
      ]
    },
    "Client": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the generated client struct."
        },
        "timeout": {
          "type": "string",
          "description": "Timeout for the generated client."
        }
      },
      "required": []
    },
    "ValidationOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "skip": {
          "type": "boolean",
          "description": "Skip specifies whether to skip Validation method generation. Defaults to false."
        },
        "simple": {
          "type": "boolean",
          "description": "Simple specifies whether to use the simple validation approach. Defaults to false. Simple validation uses validate.Struct() for all types, whereas complex validation generates custom Validate() methods."
        },
        "response": {
          "type": "boolean",
          "description": "Response specifies whether to generate Validate() methods for response types. Useful for contract testing to ensure responses match the OpenAPI spec. Defaults to false."
        }
      },
      "required": []
    },
    "HandlerOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the generated service interface. Defaults to 'Service'."
        },
        "kind": {
          "type": "string",
          "enum": ["beego", "chi", "echo", "fasthttp", "fiber", "gin", "goframe", "go-zero", "gorilla-mux", "hertz", "iris", "kratos", "std-http"],
          "description": "Router/framework to generate for. Required."
        },
        "models-package-alias": {
          "type": "string",
          "description": "Package alias to prefix model types with. Used when models are generated separately (generate.models: false). Example: 'types' will generate 'types.User' instead of 'User'."
        },
        "multipart-max-memory": {
          "type": "integer",
          "description": "Maximum memory in MB for multipart form parsing. Defaults to 32MB. Files exceeding this are stored in temp files."
        },
        "validation": {
          "$ref": "#/definitions/HandlerValidation",
          "description": "Validation options for request/response validation in handlers."
        },
        "output": {
          "$ref": "#/definitions/ScaffoldOutput",
          "description": "Output options for scaffolded handler files (service.go, middleware.go). Falls back to root output if not set."
        },
        "middleware": {
          "$ref": "#/definitions/MiddlewareOptions",
          "description": "Middleware generation options. If set, generates a scaffold middleware.go."
        },
        "server": {
          "$ref": "#/definitions/ServerOptions",
          "description": "Server generation options. If set, generates a scaffold server/main.go."
        }
      },
      "required": ["kind"]
    },
    "ScaffoldOutput": {
      "type": "object",
      "additionalProperties": false,
      "description": "Output options for scaffolded files (service.go, middleware.go).",
      "properties": {
        "directory": {
          "type": "string",
          "description": "Output directory, relative to the spec/config file location."
        },
        "package": {
          "type": "string",
          "description": "Package name for the generated file."
        },
        "overwrite": {
          "type": "boolean",
          "description": "Force regeneration of scaffold-once files (e.g., service.go, middleware.go). Normally these files are only generated if they don't exist. Defaults to false."
        }
      },
      "required": []
    },
    "MiddlewareOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "Options for generating middleware.go. Currently empty but allows for future extensibility.",
      "properties": {},
      "required": []
    },
    "MCPServerOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "Options for MCP (Model Context Protocol) server generation. MCP servers expose API operations as tools that AI assistants (Claude, Cursor, etc.) can invoke.",
      "properties": {
        "default-skip": {
          "type": "boolean",
          "description": "If true, skip all operations by default unless x-mcp.skip is explicitly false. If false (default), include all operations unless x-mcp.skip is true."
        }
      },
      "required": []
    },
    "ServerOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "directory": {
          "type": "string",
          "description": "Directory for the generated server main.go. Defaults to 'server'."
        },
        "port": {
          "type": "integer",
          "default": 8080,
          "description": "Port for the server to listen on. Defaults to 8080."
        },
        "handler-package": {
          "type": "string",
          "description": "Import path for the handler package. Required."
        }
      },
      "required": ["handler-package"]
    },
    "HandlerValidation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "request": {
          "type": "boolean",
          "description": "Request enables validation of incoming requests. Defaults to false."
        },
        "response": {
          "type": "boolean",
          "description": "Response enables validation of outgoing responses. Useful for contract testing. Defaults to false."
        }
      },
      "required": []
    }
  }
}