openapi

type Binding struct {
	// RPC is the fully-qualified method name (e.g.
	// "library.v1.BookService.GetBook"), used only in error messages.
	RPC string
	// HTTPMethod is the binding's verb (GET/POST/PUT/PATCH/DELETE). Compared
	// case-insensitively.
	HTTPMethod string
	// PathTemplate is the raw google.api.http path template, base path included
	// and no trailing slash (e.g. "/v1/libraries/{library_id}/books").
	PathTemplate string
	// SingleKey is the response's single-resource key from (jsonapi.v1.resource);
	// empty when the response carries no single resource.
	SingleKey string
	// CollectionKey is the response's collection key from (jsonapi.v1.resource);
	// empty when the response carries no collection. SingleKey and CollectionKey
	// both empty means the response carries no resource shape.
	CollectionKey string
	// Action is the (jsonapi.v1.operation){action} marker: it forces a POST with
	// a resource-shaped response to classify as ACTION rather than CREATE.
	Action bool
}

type ResourceKeys struct {
	// Type is the JSON:API data.type value (e.g. "users").
	Type string

	// SingleKey is the response property holding one resource (e.g. "user");
	// empty for collection-only resources.
	SingleKey string

	// CollectionKey is the response property holding a resource list (e.g.
	// "users"); empty for single-only resources.
	CollectionKey string
}

type Result struct {
	// Written holds the output paths of every per-service OpenAPI spec written.
	Written []string
	// Skipped holds the input swagger file paths whose proto package declared no
	// jsonapi.v1.service annotation, so no service could be resolved for them.
	Skipped []string
}

type Role string

type RouteEntry struct {
	// Method is the binding's HTTP verb (GET/POST/PUT/PATCH/DELETE), upper-cased.
	Method string
	// PathTemplate is the raw google.api.http path template for this binding,
	// base path included (e.g. "/v1/libraries/{library_id}/books").
	PathTemplate string
	// Role is the JSON:API operation role this binding classifies into (see
	// Classify).
	Role Role
	// ResourceType is the response's JSON:API `data.type` value; empty when the
	// response carries no resource.
	ResourceType string
	// SingleKey is the response property holding one resource; empty for
	// collection-only or resource-less responses.
	SingleKey string
	// CollectionKey is the response property holding a resource list; empty for
	// single-only or resource-less responses.
	CollectionKey string
	// PaginationKey is the response property holding pagination metadata;
	// carried for fidelity but inert (the collection envelope's shape is fixed).
	PaginationKey string
	// RPC is the fully-qualified method name (e.g.
	// "library.v1.BookService.GetBook").
	RPC string
	// RequestEnvelope reports whether the operation's request body should be
	// wrapped in the JSON:API {data: {type, attributes}} shape — true only for
	// the CREATE and UPDATE roles.
	RequestEnvelope bool
}

type ServiceView struct {
	// Resources holds the service's decoded JSON:API resource keys, keyed by
	// resource type.
	Resources map[string]ResourceKeys
	// BasePath is the service's REST base path (e.g. "/v1/library").
	BasePath string
}

type Violation struct {
	// RPC is the fully-qualified method name (e.g.
	// "library.v1.BookService.MarkRead").
	RPC string
	// Reason is why the RPC is unclassifiable — the classifier's message, which
	// names the RPC, method, and path so the failure points at the exact contract.
	Reason string
}