|
| 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 library for analyzing, flattening, merging (mixin), and fixing |
| 8 | +[Swagger 2.0](https://swagger.io/specification/v2/) specifications. Built on top of |
| 9 | +`go-openapi/spec`, it is a central utility in the go-swagger ecosystem for code generation |
| 10 | +and validation tooling. |
| 11 | + |
| 12 | +Mono-repo with `go.work` tying together modules: root (`github.com/go-openapi/analysis`) and `internal/testintegration`. |
| 13 | + |
| 14 | +See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details. |
| 15 | + |
| 16 | +### Package layout |
| 17 | + |
| 18 | +| File | Contents | |
| 19 | +|------|----------| |
| 20 | +| `doc.go` | Package-level godoc | |
| 21 | +| `analyzer.go` | Core `Spec` type (analyzed spec index), `New()`, security/consumer/producer queries, operation lookups, ref/pattern/enum collection | |
| 22 | +| `schema.go` | Schema classification: `Schema()`, `AnalyzedSchema` (IsKnownType, IsArray, IsMap, IsTuple, IsBaseType, IsEnum, …) | |
| 23 | +| `flatten.go` | `Flatten(FlattenOpts)` — multi-step pipeline: expand → normalize → name inline schemas → strip OAIGen → remove unused | |
| 24 | +| `flatten_options.go` | `FlattenOpts` configuration struct | |
| 25 | +| `flatten_name.go` | `InlineSchemaNamer`, `GenLocation()` — derives stable definition names from JSON Pointer paths | |
| 26 | +| `mixin.go` | `Mixin(primary, mixins...)` — merges paths, definitions, parameters, responses, security, tags; returns collision warnings | |
| 27 | +| `fixer.go` | `FixEmptyResponseDescriptions()` — patches empty response descriptions from Go JSON unmarshalling quirks | |
| 28 | +| `errors.go` | Sentinel errors (`ErrAnalysis`, `ErrNoSchema`) and error factory functions | |
| 29 | +| `debug.go` | Debug logger wired to `SWAGGER_DEBUG` env var | |
| 30 | + |
| 31 | +### Internal packages (`internal/`) |
| 32 | + |
| 33 | +| Package | Contents | |
| 34 | +|---------|----------| |
| 35 | +| `internal/debug` | `GetLogger()` — conditional debug logging | |
| 36 | +| `internal/antest` | Test helpers: `LoadSpec()`, `LoadOrFail()`, `AsJSON()`, `LongTestsEnabled()` | |
| 37 | +| `internal/flatten/normalize` | `RebaseRef()`, `Path()` — canonical ref rebasing | |
| 38 | +| `internal/flatten/operations` | `OpRef`, `GatherOperations()`, `AllOpRefsByRef()` | |
| 39 | +| `internal/flatten/replace` | Low-level ref rewriting: `RewriteSchemaToRef()`, `UpdateRef()`, `DeepestRef()` | |
| 40 | +| `internal/flatten/schutils` | `Save()`, `Clone()` — schema storage and deep-copy helpers | |
| 41 | +| `internal/flatten/sortref` | `SplitKey` (parsed JSON pointer), `DepthFirst()`, `TopmostFirst()`, `ReverseIndex()` | |
| 42 | + |
| 43 | +### Key API |
| 44 | + |
| 45 | +- `New(*spec.Swagger) *Spec` — build an analyzed index from a parsed spec |
| 46 | +- `Spec` methods — `Operations()`, `AllDefinitions()`, `AllRefs()`, `ConsumesFor()`, `ProducesFor()`, `ParametersFor()`, `SecurityRequirementsFor()`, pattern/enum enumeration |
| 47 | +- `Schema(SchemaOpts) (*AnalyzedSchema, error)` — classify a schema (array, map, tuple, base type, etc.) |
| 48 | +- `Flatten(FlattenOpts) error` — flatten/expand a spec (inline schemas → definitions, remote refs → local) |
| 49 | +- `Mixin(primary, mixins...) []string` — merge multiple specs, returning collision warnings |
| 50 | +- `FixEmptyResponseDescriptions(*spec.Swagger)` — patch empty response descriptions |
| 51 | + |
| 52 | +### Dependencies |
| 53 | + |
| 54 | +- `github.com/go-openapi/spec` — Swagger 2.0 document model |
| 55 | +- `github.com/go-openapi/jsonpointer` — JSON pointer navigation (ref rewriting) |
| 56 | +- `github.com/go-openapi/strfmt` — string format types |
| 57 | +- `github.com/go-openapi/swag/jsonutils` — JSON utilities |
| 58 | +- `github.com/go-openapi/swag/loading` — remote spec loading |
| 59 | +- `github.com/go-openapi/swag/mangling` — name mangling for Go identifiers |
| 60 | +- `github.com/go-openapi/testify/v2` — test-only assertions |
| 61 | + |
| 62 | +### Notable design decisions |
| 63 | + |
| 64 | +- **Flatten is a multi-step pipeline** (expand → normalize refs → name inline schemas → strip |
| 65 | + OAIGen artifacts → remove unused). It distinguishes "expand" mode (fully dereference) from |
| 66 | + "minimal" flatten (only pull in remote refs). |
| 67 | +- **OAIGen naming convention** — when flattening creates a definition from an anonymous schema |
| 68 | + and no better name can be derived, it uses an `OAIGen` prefix as a sentinel. A post-pass |
| 69 | + attempts to resolve these into better names. |
| 70 | +- **Mixin returns collision strings, not errors** — duplicate paths/definitions are soft failures |
| 71 | + reported as warning strings, letting callers decide severity. |
| 72 | +- **`FixEmptyResponseDescriptions` compensates for Go JSON marshalling** — unmarshalling can |
| 73 | + produce `Response` objects with empty descriptions; this fixer patches them. |
0 commit comments