Keep track of API changes with CI (#732)

.github/docs/openapi2.txt

@@ -0,0 +1,9 @@
+type Header struct{ ... }
+type Operation struct{ ... }
+type Parameter struct{ ... }
+type Parameters []*Parameter
+type PathItem struct{ ... }
+type Response struct{ ... }
+type SecurityRequirements []map[string][]string
+type SecurityScheme struct{ ... }
+type T struct{ ... }

.github/docs/openapi2conv.txt

@@ -0,0 +1,25 @@
+func FromV3(doc3 *openapi3.T) (*openapi2.T, error)
+func FromV3Headers(defs openapi3.Headers, components *openapi3.Components) (map[string]*openapi2.Header, error)
+func FromV3Operation(doc3 *openapi3.T, operation *openapi3.Operation) (*openapi2.Operation, error)
+func FromV3Parameter(ref *openapi3.ParameterRef, components *openapi3.Components) (*openapi2.Parameter, error)
+func FromV3PathItem(doc3 *openapi3.T, pathItem *openapi3.PathItem) (*openapi2.PathItem, error)
+func FromV3Ref(ref string) string
+func FromV3RequestBody(name string, requestBodyRef *openapi3.RequestBodyRef, ...) (*openapi2.Parameter, error)
+func FromV3RequestBodyFormData(mediaType *openapi3.MediaType) openapi2.Parameters
+func FromV3Response(ref *openapi3.ResponseRef, components *openapi3.Components) (*openapi2.Response, error)
+func FromV3Responses(responses map[string]*openapi3.ResponseRef, components *openapi3.Components) (map[string]*openapi2.Response, error)
+func FromV3SchemaRef(schema *openapi3.SchemaRef, components *openapi3.Components) (*openapi3.SchemaRef, *openapi2.Parameter)
+func FromV3Schemas(schemas map[string]*openapi3.SchemaRef, components *openapi3.Components) (map[string]*openapi3.SchemaRef, map[string]*openapi2.Parameter)
+func FromV3SecurityRequirements(requirements openapi3.SecurityRequirements) openapi2.SecurityRequirements
+func FromV3SecurityScheme(doc3 *openapi3.T, ref *openapi3.SecuritySchemeRef) (*openapi2.SecurityScheme, error)
+func ToV3(doc2 *openapi2.T) (*openapi3.T, error)
+func ToV3Headers(defs map[string]*openapi2.Header) openapi3.Headers
+func ToV3Operation(doc2 *openapi2.T, components *openapi3.Components, pathItem *openapi2.PathItem, ...) (*openapi3.Operation, error)
+func ToV3Parameter(components *openapi3.Components, parameter *openapi2.Parameter, ...) (*openapi3.ParameterRef, *openapi3.RequestBodyRef, ...)
+func ToV3PathItem(doc2 *openapi2.T, components *openapi3.Components, pathItem *openapi2.PathItem, ...) (*openapi3.PathItem, error)
+func ToV3Ref(ref string) string
+func ToV3Response(response *openapi2.Response, produces []string) (*openapi3.ResponseRef, error)
+func ToV3SchemaRef(schema *openapi3.SchemaRef) *openapi3.SchemaRef
+func ToV3Schemas(defs map[string]*openapi3.SchemaRef) map[string]*openapi3.SchemaRef
+func ToV3SecurityRequirements(requirements openapi2.SecurityRequirements) openapi3.SecurityRequirements
+func ToV3SecurityScheme(securityScheme *openapi2.SecurityScheme) (*openapi3.SecuritySchemeRef, error)

.github/docs/openapi3.txt

@@ -0,0 +1,153 @@
+const ParameterInPath = "path" ...
+const TypeArray = "array" ...
+const FormatOfStringForUUIDOfRFC4122 = `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$` ...
+const SerializationSimple = "simple" ...
+var SchemaErrorDetailsDisabled = false ...
+var CircularReferenceCounter = 3
+var CircularReferenceError = "kin-openapi bug found: circular schema reference not handled"
+var DefaultReadFromURI = URIMapCache(ReadFromURIs(ReadFromHTTP(http.DefaultClient), ReadFromFile))
+var ErrURINotSupported = errors.New("unsupported URI")
+var IdentifierRegExp = regexp.MustCompile(identifierPattern)
+var SchemaStringFormats = make(map[string]Format, 4)
+func BoolPtr(value bool) *bool
+func DefaultRefNameResolver(ref string) string
+func DefineIPv4Format()
+func DefineIPv6Format()
+func DefineStringFormat(name string, pattern string)
+func DefineStringFormatCallback(name string, callback FormatCallback)
+func Float64Ptr(value float64) *float64
+func Int64Ptr(value int64) *int64
+func ReadFromFile(loader *Loader, location *url.URL) ([]byte, error)
+func RegisterArrayUniqueItemsChecker(fn SliceUniqueItemsChecker)
+func Uint64Ptr(value uint64) *uint64
+func ValidateIdentifier(value string) error
+func WithValidationOptions(ctx context.Context, opts ...ValidationOption) context.Context
+type AdditionalProperties struct{ ... }
+type Callback map[string]*PathItem
+type CallbackRef struct{ ... }
+type Callbacks map[string]*CallbackRef
+type Components struct{ ... }
+    func NewComponents() Components
+type Contact struct{ ... }
+type Content map[string]*MediaType
+    func NewContent() Content
+    func NewContentWithFormDataSchema(schema *Schema) Content
+    func NewContentWithFormDataSchemaRef(schema *SchemaRef) Content
+    func NewContentWithJSONSchema(schema *Schema) Content
+    func NewContentWithJSONSchemaRef(schema *SchemaRef) Content
+    func NewContentWithSchema(schema *Schema, consumes []string) Content
+    func NewContentWithSchemaRef(schema *SchemaRef, consumes []string) Content
+type Discriminator struct{ ... }
+type Encoding struct{ ... }
+    func NewEncoding() *Encoding
+type Example struct{ ... }
+    func NewExample(value interface{}) *Example
+type ExampleRef struct{ ... }
+type Examples map[string]*ExampleRef
+type ExternalDocs struct{ ... }
+type Format struct{ ... }
+type FormatCallback func(value string) error
+type Header struct{ ... }
+type HeaderRef struct{ ... }
+type Headers map[string]*HeaderRef
+type Info struct{ ... }
+type License struct{ ... }
+type Link struct{ ... }
+type LinkRef struct{ ... }
+type Links map[string]*LinkRef
+type Loader struct{ ... }
+    func NewLoader() *Loader
+type MediaType struct{ ... }
+    func NewMediaType() *MediaType
+type MultiError []error
+type OAuthFlow struct{ ... }
+type OAuthFlows struct{ ... }
+type Operation struct{ ... }
+    func NewOperation() *Operation
+type Parameter struct{ ... }
+    func NewCookieParameter(name string) *Parameter
+    func NewHeaderParameter(name string) *Parameter
+    func NewPathParameter(name string) *Parameter
+    func NewQueryParameter(name string) *Parameter
+type ParameterRef struct{ ... }
+type Parameters []*ParameterRef
+    func NewParameters() Parameters
+type ParametersMap map[string]*ParameterRef
+type PathItem struct{ ... }
+type Paths map[string]*PathItem
+type ReadFromURIFunc func(loader *Loader, url *url.URL) ([]byte, error)
+    func ReadFromHTTP(cl *http.Client) ReadFromURIFunc
+    func ReadFromURIs(readers ...ReadFromURIFunc) ReadFromURIFunc
+    func URIMapCache(reader ReadFromURIFunc) ReadFromURIFunc
+type Ref struct{ ... }
+type RefNameResolver func(string) string
+type RequestBodies map[string]*RequestBodyRef
+type RequestBody struct{ ... }
+    func NewRequestBody() *RequestBody
+type RequestBodyRef struct{ ... }
+type Response struct{ ... }
+    func NewResponse() *Response
+type ResponseRef struct{ ... }
+type Responses map[string]*ResponseRef
+    func NewResponses() Responses
+type Schema struct{ ... }
+    func NewAllOfSchema(schemas ...*Schema) *Schema
+    func NewAnyOfSchema(schemas ...*Schema) *Schema
+    func NewArraySchema() *Schema
+    func NewBoolSchema() *Schema
+    func NewBytesSchema() *Schema
+    func NewDateTimeSchema() *Schema
+    func NewFloat64Schema() *Schema
+    func NewInt32Schema() *Schema
+    func NewInt64Schema() *Schema
+    func NewIntegerSchema() *Schema
+    func NewObjectSchema() *Schema
+    func NewOneOfSchema(schemas ...*Schema) *Schema
+    func NewSchema() *Schema
+    func NewStringSchema() *Schema
+    func NewUUIDSchema() *Schema
+type SchemaError struct{ ... }
+type SchemaRef struct{ ... }
+    func NewSchemaRef(ref string, value *Schema) *SchemaRef
+type SchemaRefs []*SchemaRef
+type SchemaValidationOption func(*schemaValidationSettings)
+    func DefaultsSet(f func()) SchemaValidationOption
+    func DisablePatternValidation() SchemaValidationOption
+    func EnableFormatValidation() SchemaValidationOption
+    func FailFast() SchemaValidationOption
+    func MultiErrors() SchemaValidationOption
+    func SetSchemaErrorMessageCustomizer(f func(err *SchemaError) string) SchemaValidationOption
+    func VisitAsRequest() SchemaValidationOption
+    func VisitAsResponse() SchemaValidationOption
+type Schemas map[string]*SchemaRef
+type SecurityRequirement map[string][]string
+    func NewSecurityRequirement() SecurityRequirement
+type SecurityRequirements []SecurityRequirement
+    func NewSecurityRequirements() *SecurityRequirements
+type SecurityScheme struct{ ... }
+    func NewCSRFSecurityScheme() *SecurityScheme
+    func NewJWTSecurityScheme() *SecurityScheme
+    func NewOIDCSecurityScheme(oidcUrl string) *SecurityScheme
+    func NewSecurityScheme() *SecurityScheme
+type SecuritySchemeRef struct{ ... }
+type SecuritySchemes map[string]*SecuritySchemeRef
+type SerializationMethod struct{ ... }
+type Server struct{ ... }
+type ServerVariable struct{ ... }
+type Servers []*Server
+type SliceUniqueItemsChecker func(items []interface{}) bool
+type T struct{ ... }
+type Tag struct{ ... }
+type Tags []*Tag
+type ValidationOption func(options *ValidationOptions)
+    func AllowExtraSiblingFields(fields ...string) ValidationOption
+    func DisableExamplesValidation() ValidationOption
+    func DisableSchemaDefaultsValidation() ValidationOption
+    func DisableSchemaFormatValidation() ValidationOption
+    func DisableSchemaPatternValidation() ValidationOption
+    func EnableExamplesValidation() ValidationOption
+    func EnableSchemaDefaultsValidation() ValidationOption
+    func EnableSchemaFormatValidation() ValidationOption
+    func EnableSchemaPatternValidation() ValidationOption
+type ValidationOptions struct{ ... }
+type XML struct{ ... }

.github/docs/openapi3filter.txt

@@ -0,0 +1,55 @@
+const ErrCodeOK = 0 ...
+var DefaultOptions = &Options{}
+var ErrAuthenticationServiceMissing = errors.New("missing AuthenticationFunc")
+var ErrInvalidEmptyValue = errors.New("empty value is not allowed")
+var ErrInvalidRequired = errors.New("value is required but missing")
+var JSONPrefixes = []string{ ... }
+func DefaultErrorEncoder(_ context.Context, err error, w http.ResponseWriter)
+func FileBodyDecoder(body io.Reader, header http.Header, schema *openapi3.SchemaRef, ...) (interface{}, error)
+func NoopAuthenticationFunc(context.Context, *AuthenticationInput) error
+func RegisterBodyDecoder(contentType string, decoder BodyDecoder)
+func RegisterBodyEncoder(contentType string, encoder BodyEncoder)
+func TrimJSONPrefix(data []byte) []byte
+func UnregisterBodyDecoder(contentType string)
+func UnregisterBodyEncoder(contentType string)
+func ValidateParameter(ctx context.Context, input *RequestValidationInput, ...) error
+func ValidateRequest(ctx context.Context, input *RequestValidationInput) (err error)
+func ValidateRequestBody(ctx context.Context, input *RequestValidationInput, ...) error
+func ValidateResponse(ctx context.Context, input *ResponseValidationInput) error
+func ValidateSecurityRequirements(ctx context.Context, input *RequestValidationInput, ...) error
+func ZipFileBodyDecoder(body io.Reader, header http.Header, schema *openapi3.SchemaRef, ...) (interface{}, error)
+type AuthenticationFunc func(context.Context, *AuthenticationInput) error
+type AuthenticationInput struct{ ... }
+type BodyDecoder func(io.Reader, http.Header, *openapi3.SchemaRef, EncodingFn) (interface{}, error)
+    func RegisteredBodyDecoder(contentType string) BodyDecoder
+type BodyEncoder func(body interface{}) ([]byte, error)
+    func RegisteredBodyEncoder(contentType string) BodyEncoder
+type ContentParameterDecoder func(param *openapi3.Parameter, values []string) (interface{}, *openapi3.Schema, error)
+type CustomSchemaErrorFunc func(err *openapi3.SchemaError) string
+type EncodingFn func(partName string) *openapi3.Encoding
+type ErrCode int
+type ErrFunc func(w http.ResponseWriter, status int, code ErrCode, err error)
+type ErrorEncoder func(ctx context.Context, err error, w http.ResponseWriter)
+type Headerer interface{ ... }
+type LogFunc func(message string, err error)
+type Options struct{ ... }
+type ParseError struct{ ... }
+type ParseErrorKind int
+    const KindOther ParseErrorKind = iota ...
+type RequestError struct{ ... }
+type RequestValidationInput struct{ ... }
+type ResponseError struct{ ... }
+type ResponseValidationInput struct{ ... }
+type SecurityRequirementsError struct{ ... }
+type StatusCoder interface{ ... }
+type ValidationError struct{ ... }
+type ValidationErrorEncoder struct{ ... }
+type ValidationErrorSource struct{ ... }
+type ValidationHandler struct{ ... }
+type Validator struct{ ... }
+    func NewValidator(router routers.Router, options ...ValidatorOption) *Validator
+type ValidatorOption func(*Validator)
+    func OnErr(f ErrFunc) ValidatorOption
+    func OnLog(f LogFunc) ValidatorOption
+    func Strict(strict bool) ValidatorOption
+    func ValidationOptions(options Options) ValidatorOption

.github/docs/openapi3gen.txt

@@ -0,0 +1,11 @@
+var RefSchemaRef = openapi3.NewSchemaRef("Ref", ...)
+func NewSchemaRefForValue(value interface{}, schemas openapi3.Schemas, opts ...Option) (*openapi3.SchemaRef, error)
+type CycleError struct{}
+type ExcludeSchemaSentinel struct{}
+type Generator struct{ ... }
+    func NewGenerator(opts ...Option) *Generator
+type Option func(*generatorOpt)
+    func SchemaCustomizer(sc SchemaCustomizerFn) Option
+    func ThrowErrorOnCycle() Option
+    func UseAllExportedFields() Option
+type SchemaCustomizerFn func(name string, t reflect.Type, tag reflect.StructTag, schema *openapi3.Schema) error

.github/docs/routers.txt

@@ -0,0 +1,5 @@
+var ErrMethodNotAllowed error = &RouteError{ ... }
+var ErrPathNotFound error = &RouteError{ ... }
+type Route struct{ ... }
+type RouteError struct{ ... }
+type Router interface{ ... }

.github/docs/routers_gorillamux.txt

@@ -0,0 +1,2 @@
+func NewRouter(doc *openapi3.T) (routers.Router, error)
+type Router struct{ ... }

.github/docs/routers_legacy.txt

@@ -0,0 +1,3 @@
+func NewRouter(doc *openapi3.T, opts ...openapi3.ValidationOption) (routers.Router, error)
+type Router struct{ ... }
+type Routers []*Router

.github/docs/routers_legacy_pathpattern.txt

@@ -0,0 +1,9 @@
+const SuffixKindConstant = SuffixKind(iota) ...
+var DefaultOptions = &Options{ ... }
+func EqualSuffix(a, b Suffix) bool
+func PathFromHost(host string, specialDashes bool) string
+type Node struct{ ... }
+type Options struct{ ... }
+type Suffix struct{ ... }
+type SuffixKind int
+type SuffixList []Suffix

.github/workflows/go.yml

@@ -57,6 +57,9 @@ jobs:
         ./refs.sh | tee openapi3/refs.go
         git --no-pager diff --exit-code
 
+    - name: Check docsgen
+      run: ./docs.sh
+
     - run: go mod download && go mod tidy && go mod verify
     - run: git --no-pager diff --exit-code
 

docs.sh

@@ -0,0 +1,25 @@
+#!/bin/bash -eux
+set -o pipefail
+
+outdir=.github/docs
+mkdir -p "$outdir"
+for pkgpath in $(git ls-files | grep  / | while read -r path; do dirname "$path"; done | sort -u | grep -vE '[.]git|testdata|cmd/'); do
+	go doc -short "./$pkgpath" | tee "$outdir/${pkgpath////_}.txt"
+done
+
+git --no-pager diff -- .github/docs/
+
+count_missing_mentions() {
+	local errors=0
+	for thing in $(git --no-pager diff -- .github/docs/ \
+		| grep -vE '[-]{3}' \
+		| grep -Eo '^-[^ ]+ ([^ (]+)[ (]' \
+		| sed 's%(% %' \
+		| cut -d' ' -f2); do
+		if ! grep -A999999 '## Sub-v0 breaking API changes' README.md | grep -F "$thing"; then
+			((errors++)) || true
+		fi
+	done
+	return $errors
+}
+count_missing_mentions

openapi3filter/req_resp_decoder.go

@@ -1236,7 +1236,7 @@ func ZipFileBodyDecoder(body io.Reader, header http.Header, schema *openapi3.Sch
 
 	const bufferSize = 256
 	content := make([]byte, 0, bufferSize*len(zr.File))
-	buffer := make([]byte, bufferSize)
+	buffer := make([]byte /*0,*/, bufferSize)
 
 	for _, f := range zr.File {
 		err := func() error {

openapi3filter/validation_error_test.go

@@ -556,7 +556,7 @@ func TestValidationErrorEncoder(t *testing.T) {
 
 func buildValidationHandler(tt *validationTest) (*ValidationHandler, error) {
 	if tt.fields.File == "" {
-		tt.fields.File = "fixtures/petstore.json"
+		tt.fields.File = "testdata/fixtures/petstore.json"
 	}
 	h := &ValidationHandler{
 		Handler:      tt.fields.Handler,
@@ -600,7 +600,7 @@ func runTest_ServeHTTP(t *testing.T, handler http.Handler, encoder ErrorEncoder,
 	h := &ValidationHandler{
 		Handler:      handler,
 		ErrorEncoder: encoder,
-		File:         "fixtures/petstore.json",
+		File:         "testdata/fixtures/petstore.json",
 	}
 	err := h.Load()
 	require.NoError(t, err)
@@ -612,7 +612,7 @@ func runTest_ServeHTTP(t *testing.T, handler http.Handler, encoder ErrorEncoder,
 func runTest_Middleware(t *testing.T, handler http.Handler, encoder ErrorEncoder, req *http.Request) *http.Response {
 	h := &ValidationHandler{
 		ErrorEncoder: encoder,
-		File:         "fixtures/petstore.json",
+		File:         "testdata/fixtures/petstore.json",
 	}
 	err := h.Load()
 	require.NoError(t, err)