Skip to content

copilot-instructions.md

Latest commit

 

History

History
61 lines (45 loc) · 2.58 KB

copilot-instructions.md

File metadata and controls

61 lines (45 loc) · 2.58 KB

Copilot Instructions — spec

Project Overview

Go types modeling the Swagger 2.0 / OpenAPI 2.0 specification. This package is the foundational data model for the go-swagger ecosystem — every specification object (Swagger, Schema, Operation, Parameter, etc.) is a Go struct with JSON round-trip serialization. It also includes a $ref expansion engine for resolving JSON References across local and remote documents.

Single module: github.com/go-openapi/spec.

Package layout (single package)

File Contents
swagger.go Root Swagger type (top-level spec object)
schema.go Schema (JSON Schema subset used by Swagger)
operation.go Operation (single API operation)
parameter.go Parameter (query, header, path, body, formData)
response.go, responses.go Response, Responses
ref.go Ref type, JSON Reference ($ref) handling
expander.go $ref expansion / resolution engine
normalizer.go URL/path normalization (platform-specific variants)

Key API

  • Swagger — root specification object; deserialize with json.Unmarshal
  • Schema — JSON Schema with Swagger extensions; supports allOf, $ref, validations
  • Ref / MustCreateRef(uri) — JSON Reference wrapper
  • ExpandSpec(spec, opts) — resolve all $ref nodes in a specification
  • ExpandSchema(schema, root, cache) — resolve $ref nodes in a single schema
  • ResolveRef(root, ref) / ResolveParameter / ResolveResponse — targeted resolution

Dependencies

  • github.com/go-openapi/jsonpointer — JSON Pointer (RFC 6901) navigation
  • github.com/go-openapi/jsonreference — JSON Reference parsing
  • github.com/go-openapi/swag — JSON/YAML utilities, name mangling
  • github.com/go-openapi/testify/v2 — test-only assertions (zero-dep testify fork)

Building & testing

go test ./...

Conventions

Coding conventions are found beneath .github/copilot

Summary

  • All .go files must have SPDX license headers (Apache-2.0).
  • Commits require DCO sign-off (git commit -s).
  • Linting: golangci-lint run — config in .golangci.yml (posture: default: all with explicit disables).
  • Every //nolint directive must have an inline comment explaining why.
  • Tests: go test ./.... CI runs on {ubuntu, macos, windows} x {stable, oldstable} with -race.
  • Test framework: github.com/go-openapi/testify/v2 (not stretchr/testify; testifylint does not work).

See .github/copilot/ (symlinked to .claude/rules/) for detailed rules on Go conventions, linting, testing, and contributions.