Skip to content

Commit 7262605

Browse files
fredbifredbi
authored
doc: updated documentation (#16)
* common project documentation now points toward go-openapi documents (contributing, DCO, etc) * updated agent instructions, following the big reshuffle * fixed license headers in sources * removed mention of go1.11. We're now go1.25... Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 8e16469 commit 7262605

45 files changed

Lines changed: 269 additions & 647 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 106 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,43 +9,127 @@ Go source code scanner that parses Go packages and produces [Swagger 2.0](https:
99
and extracts API metadata — routes, parameters, responses, schemas, and more — to build a complete
1010
`spec.Swagger` document. Supports Go modules (go1.11+).
1111

12-
See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
12+
See [Maintainers documentation][maintainers-doc-site] for CI/CD, release process, and repo structure details.
1313

14-
### Package layout (single package)
14+
[maintainers-doc-site]: https://go-openapi.github.io/doc-site/maintainers/index.html
15+
16+
## Package layout
17+
18+
Single Go module `github.com/go-openapi/codescan`. Public API lives at the root; implementation is
19+
split under `internal/` into three layers: **scanner** (package/AST ingestion), **parsers** (comment
20+
block parsing), and **builders** (emitting Swagger objects). A thin `ifaces` package glues parsers
21+
to builders without direct coupling.
22+
23+
### Root (public API — keep surface minimal)
24+
25+
| File | Contents |
26+
|------|----------|
27+
| `api.go` | `Run(*Options) (*spec.Swagger, error)` entry point; re-exports `Options = scanner.Options` |
28+
| `doc.go` | Package godoc |
29+
| `errors.go` | `ErrCodeScan` sentinel error |
30+
31+
### `internal/scanner/` — package loading & entity discovery
1532

1633
| File | Contents |
1734
|------|----------|
18-
| `application.go` | `Options`, `Run` entry point, `appScanner` orchestration |
19-
| `parser.go` | `sectionedParser` — comment block parsing engine (title, description, annotations) |
20-
| `parser_helpers.go` | Helpers for tag/package filtering, value extraction |
21-
| `meta.go` | Swagger info block parsing (title, version, license, contact, etc.) |
22-
| `operations.go` | Operation (route handler) annotation parsing |
23-
| `parameters.go` | Parameter annotation parsing |
24-
| `responses.go` | Response annotation parsing |
25-
| `routes.go` | Route/path discovery and matching |
26-
| `route_params.go` | Route parameter extraction |
27-
| `schema.go` | Go type → Swagger schema conversion |
28-
| `enum.go` | Enum value extraction from Go constants |
29-
| `spec.go` | Spec-level helpers |
35+
| `options.go` | `Options` struct: packages, work dir, build tags, include/exclude, feature flags |
36+
| `scan_context.go` | `ScanCtx` / `NewScanCtx` — loads Go packages via `golang.org/x/tools/go/packages` |
37+
| `index.go` | `TypeIndex` — node classification (meta/route/operation/model/parameters/response) |
38+
| `declaration.go` | `EntityDecl` — wraps a type/value declaration with its enclosing file/package |
39+
40+
### `internal/parsers/` — comment-block parsing engine
41+
42+
| File | Contents |
43+
|------|----------|
44+
| `sectioned_parser.go` | The section-driven parser that walks title/description/annotation blocks |
45+
| `parsers.go`, `parsers_helpers.go` | Dispatch + helpers for tag/package filtering, value extraction |
46+
| `tag_parsers.go`, `matchers.go` | Tag recognisers (`TypeName`, `Model`, etc.) |
3047
| `regexprs.go` | Shared regular expressions for annotation parsing |
31-
| `assertions.go` | Test assertion helpers |
48+
| `meta.go` | Swagger info-block parsing (title, version, license, contact) |
49+
| `responses.go`, `route_params.go` | Response / route-parameter annotation parsing |
50+
| `validations.go`, `extensions.go` | Validation directives, `x-*` extensions |
51+
| `enum.go`, `security.go` | Enum extraction from Go constants, security-definition blocks |
52+
| `yaml_parser.go`, `yaml_spec_parser.go` | Embedded-YAML parsing for `swagger:operation` bodies |
53+
| `lines.go`, `parsed_path_content.go` | Comment-line and path-content helpers |
54+
| `errors.go` | Sentinel errors |
55+
56+
### `internal/builders/` — Swagger object construction
57+
58+
Each sub-package owns one concern and a `taggers.go` file wiring parsers to its targets.
59+
60+
| Package | Contents |
61+
|---------|----------|
62+
| `spec` | `Builder` — top-level orchestrator producing the final `*spec.Swagger` |
63+
| `schema` | Go type → Swagger schema conversion (the largest builder; dispatch in `schema.go`) |
64+
| `operations` | Operation (route handler) annotation parsing |
65+
| `parameters` | Parameter annotation parsing |
66+
| `responses` | Response annotation parsing |
67+
| `routes` | Route/path discovery and matching |
68+
| `items` | Array-item targets (typable + validations, no own annotations) |
69+
| `resolvers` | `SwaggerSchemaForType`, identity/assertion helpers shared by builders |
70+
71+
### `internal/ifaces/` — cross-package interfaces
72+
73+
`SwaggerTypable`, `ValidationBuilder`, `OperationValidationBuilder`, `ValueParser`, `Objecter` —
74+
the glue that lets `parsers` write into any builder's target without importing concrete builders.
75+
76+
### `internal/logger/` — debug logging
77+
78+
`debug.go` — gated on `Options.Debug`.
79+
80+
### `internal/scantest/` — test utilities (do **not** import from production code)
81+
82+
| File | Contents |
83+
|------|----------|
84+
| `load.go` | `FixturesDir`, package-loading helpers |
85+
| `golden.go` | `CompareOrDumpJSON` — golden-file comparison honoring `UPDATE_GOLDEN=1` |
86+
| `property.go` | Assertion helpers for property-shape checks |
87+
| `classification/` | Reusable assertions over the classification fixture |
88+
| `mocks/` | Minimal mock implementations of `ifaces` interfaces |
89+
90+
### `internal/integration/` — black-box integration tests
91+
92+
Scans fixture trees and compares against `fixtures/integration/golden/*.json`. Tests for enhancements,
93+
malformed input, the petstore, aliased schemas, go123-specific forms, and cross-feature coverage.
94+
95+
### `fixtures/`
96+
97+
- `fixtures/goparsing/...` — historic corpus: classification, petstore, go118/go119/go123 variants, invalid inputs.
98+
- `fixtures/enhancements/...` — one sub-directory per isolated branch-coverage scenario (e.g. `swagger-type-array`,
99+
`alias-expand`, `allof-edges`, `named-basic`, `interface-methods`).
100+
- `fixtures/integration/golden/*.json` — captured Swagger output for golden comparisons.
101+
- `fixtures/bugs/...` — minimised repros for specific upstream bug IDs.
32102

33-
### Key API
103+
## Key API
34104

35-
- `Run(*Options) (*spec.Swagger, error)` — the main entry point: scan Go packages and produce a Swagger spec
36-
- `Options` — configuration: packages to scan, build tags, base swagger spec to overlay
105+
- `codescan.Run(*Options) (*spec.Swagger, error)` — the main entry point.
106+
- `codescan.Options` — configuration. Notable fields beyond `Packages`/`WorkDir`:
107+
- `ScanModels` — also emit definitions for `swagger:model` types.
108+
- `InputSpec` — overlay: merge discoveries on top of an existing spec.
109+
- `BuildTags`, `Include`/`Exclude`, `IncludeTags`/`ExcludeTags`, `ExcludeDeps` — scope control.
110+
- `RefAliases`, `TransparentAliases`, `DescWithRef` — alias handling knobs.
111+
- `SetXNullableForPointers` — emit `x-nullable: true` on pointer fields.
112+
- `SkipExtensions` — suppress `x-go-*` vendor extensions.
113+
- `Debug` — verbose logging via `internal/logger`.
37114

38-
### Dependencies
115+
## Dependencies
39116

40117
- `github.com/go-openapi/loads` — loading base Swagger specs
41118
- `github.com/go-openapi/spec` — Swagger 2.0 spec types
42119
- `github.com/go-openapi/swag` — string/JSON utilities
43120
- `golang.org/x/tools` — Go package loading (`packages.Load`)
44-
- `github.com/go-openapi/testify/v2` — test-only assertions
121+
- `github.com/go-openapi/testify/v2` — test-only assertions (zero-dep fork of `stretchr/testify`)
45122

46-
### Notable design decisions
123+
## Notable design decisions
47124

48125
- Uses `golang.org/x/tools/go/packages` for module-aware package loading.
49126
- Comment annotations follow the go-swagger convention (`swagger:route`, `swagger:operation`,
50127
`swagger:parameters`, `swagger:response`, `swagger:model`, etc.).
51-
- The scanner works on the AST level — it does not execute or compile the scanned code.
128+
- The scanner works at the AST / `go/types` level — it never executes or compiles scanned code.
129+
- Parsers never import builders; they write through the interfaces in `internal/ifaces`.
130+
When adding a new annotation, extend the relevant builder's `taggers.go` rather than reaching
131+
into parser internals.
132+
- Test helpers live in `internal/scantest` and are never imported from production code (guarded by
133+
build-tag-free test files). Do not widen production API to satisfy a test — use `export_test.go`
134+
or an integration test instead.
135+
- Golden-file comparisons go through `scantest.CompareOrDumpJSON`; regenerate with `UPDATE_GOLDEN=1 go test ./...`.

0 commit comments

Comments
 (0)