|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Go types modeling the [Swagger 2.0 / OpenAPI 2.0](https://swagger.io/specification/v2/) |
| 8 | +specification. Every object in the spec --- `Swagger`, `Info`, `PathItem`, `Operation`, |
| 9 | +`Parameter`, `Schema`, `Response`, `Header`, `SecurityScheme`, etc. --- has a corresponding |
| 10 | +Go struct with JSON serialization (`encoding/json`) that round-trips through the spec's |
| 11 | +JSON representation. |
| 12 | + |
| 13 | +This package is the **foundational data model** for the |
| 14 | +[go-swagger](https://github.com/go-swagger/go-swagger) ecosystem. Higher-level packages |
| 15 | +(`analysis`, `loads`, `validate`, `runtime`) consume these types to load, analyze, validate, |
| 16 | +and serve Swagger specifications. Because it sits at the bottom of the dependency graph, |
| 17 | +changes here ripple through the entire ecosystem. |
| 18 | + |
| 19 | +Key capabilities beyond plain structs: |
| 20 | + |
| 21 | +- **`$ref` resolution** --- the `Ref` type wraps JSON Reference pointers; the `expander` |
| 22 | + resolves `$ref` nodes (local, remote, circular) into fully expanded specs. |
| 23 | +- **Schema composition** --- `Schema` supports `allOf`, `additionalProperties`, |
| 24 | + `additionalItems`, and JSON Schema validations (`minimum`, `pattern`, `enum`, etc.). |
| 25 | +- **URL normalization** --- cross-platform path/URL normalization for `$ref` targets. |
| 26 | +- **Embedded spec** --- a copy of the Swagger 2.0 JSON Schema is embedded via `go:embed` |
| 27 | + for offline use. |
| 28 | + |
| 29 | +See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details. |
| 30 | + |
| 31 | +### Package layout (single package) |
| 32 | + |
| 33 | +| File | Contents | |
| 34 | +|------|----------| |
| 35 | +| `swagger.go` | Root `Swagger` type (top-level spec object) | |
| 36 | +| `info.go` | `Info`, `ContactInfo`, `LicenseInfo` | |
| 37 | +| `paths.go` | `Paths` (map of path patterns to `PathItem`) | |
| 38 | +| `path_item.go` | `PathItem` (GET/PUT/POST/DELETE/... operations per path) | |
| 39 | +| `operation.go` | `Operation` (single API operation) | |
| 40 | +| `parameter.go` | `Parameter` (query, header, path, body, formData) | |
| 41 | +| `header.go` | `Header` | |
| 42 | +| `response.go`, `responses.go` | `Response`, `Responses` | |
| 43 | +| `schema.go` | `Schema` (JSON Schema subset used by Swagger) | |
| 44 | +| `security_scheme.go` | `SecurityScheme` | |
| 45 | +| `items.go` | `Items` (non-body parameter schema) | |
| 46 | +| `ref.go` | `Ref` type, JSON Reference (`$ref`) handling | |
| 47 | +| `expander.go` | `$ref` expansion / resolution engine | |
| 48 | +| `normalizer.go` | URL/path normalization (platform-specific variants) | |
| 49 | +| `cache.go` | Resolution cache for expanded specs | |
| 50 | +| `validations.go` | Common validation properties shared across types | |
| 51 | +| `properties.go` | `SchemaProperties` ordered map | |
| 52 | +| `embed.go` | Embedded Swagger 2.0 JSON Schema (`go:embed`) | |
| 53 | +| `spec.go` | `MustLoadSwagger20Schema()` loader | |
| 54 | +| `external_docs.go` | `ExternalDocumentation` | |
| 55 | +| `tag.go` | `Tag` | |
| 56 | +| `xml_object.go` | `XMLObject` | |
| 57 | +| `debug.go` | Debug logging helpers | |
| 58 | + |
| 59 | +### Key API |
| 60 | + |
| 61 | +- `Swagger` --- root specification object; deserialize with `json.Unmarshal` |
| 62 | +- `Schema` --- JSON Schema with Swagger extensions; supports `allOf`, `$ref`, validations |
| 63 | +- `Ref` / `MustCreateRef(uri)` --- JSON Reference wrapper |
| 64 | +- `ExpandSpec(spec, opts)` --- resolve all `$ref` nodes in a specification |
| 65 | +- `ExpandSchema(schema, root, cache)` --- resolve `$ref` nodes in a single schema |
| 66 | +- `ResolveRef(root, ref)` / `ResolveParameter` / `ResolveResponse` --- targeted resolution |
| 67 | + |
| 68 | +### Dependencies |
| 69 | + |
| 70 | +- `github.com/go-openapi/jsonpointer` --- JSON Pointer (RFC 6901) navigation |
| 71 | +- `github.com/go-openapi/jsonreference` --- JSON Reference parsing |
| 72 | +- `github.com/go-openapi/swag` --- JSON/YAML utilities, name mangling |
| 73 | +- `github.com/go-openapi/testify/v2` --- test-only assertions (zero-dep testify fork) |
| 74 | + |
| 75 | +### Notable historical design decisions |
| 76 | + |
| 77 | +- **Mixin of spec types and `$ref`** --- many types embed both their data fields and a `Ref` |
| 78 | + field. When `$ref` is present, the data fields are ignored per the Swagger specification. |
| 79 | + This is modeled by custom `MarshalJSON`/`UnmarshalJSON` on each type. |
| 80 | +- **`VendorExtensible`** --- most types embed `VendorExtensible` to capture `x-` extension |
| 81 | + fields as `map[string]any`. |
| 82 | +- **`SchemaProperties` as ordered slice** --- schema properties are stored as a slice of |
| 83 | + key-value pairs (not a map) to preserve declaration order during round-trip serialization. |
| 84 | +- **Platform-specific normalization** --- Windows path handling differs from Unix; separate |
| 85 | + `normalizer_windows.go` / `normalizer_nonwindows.go` files handle this. |
0 commit comments