Define missing XML in schema, minor fixes and doc additions (#508)

.github/workflows/go.yml

@@ -47,26 +47,25 @@ jobs:
         path: ${{ steps.go-cache-paths.outputs.go-mod }}
         key: ${{ runner.os }}-go-${{ matrix.go }}-mod-${{ hashFiles('**/go.sum') }}
 
+    - if: runner.os == 'Linux'
+      run: sudo apt install silversearcher-ag
+
     - uses: actions/checkout@v2
 
     - run: go mod download && go mod tidy && go mod verify
-    - if: runner.os == 'Linux'
-      run: git --no-pager diff && [[ $(git --no-pager diff --name-only | wc -l) = 0 ]]
+    - run: git --no-pager diff --exit-code
 
     - run: go vet ./...
-    - if: runner.os == 'Linux'
-      run: git --no-pager diff && [[ $(git --no-pager diff --name-only | wc -l) = 0 ]]
+    - run: git --no-pager diff --exit-code
 
     - run: go fmt ./...
-    - if: runner.os == 'Linux'
-      run: git --no-pager diff && [[ $(git --no-pager diff --name-only | wc -l) = 0 ]]
+    - run: git --no-pager diff --exit-code
 
     - run: go test ./...
     - run: go test -v -run TestRaceyPatternSchema -race ./...
       env:
         CGO_ENABLED: '1'
-    - if: runner.os == 'Linux'
-      run: git --no-pager diff && [[ $(git --no-pager diff --name-only | wc -l) = 0 ]]
+    - run: git --no-pager diff --exit-code
 
     - if: runner.os == 'Linux'
       name: Errors must not be capitalized https://github.com/golang/go/wiki/CodeReviewComments#error-strings
@@ -77,3 +76,61 @@ jobs:
       name: Did you mean %q
       run: |
         ! git grep -E "'[%].'"
+
+    - if: runner.os == 'Linux'
+      name: Also add yaml tags
+      run: |
+        ! git grep -InE 'json:"' | grep -v _test.go | grep -v yaml:
+
+    - if: runner.os == 'Linux'
+      name: Missing specification object link to definition
+      run: |
+        [[ 30 -eq $(git grep -InE '^// See https:.+OpenAPI-Specification.+3[.]0[.]3[.]md#.+bject$' openapi3/*.go | grep -v _test.go | grep -v doc.go | wc -l) ]]
+
+    - if: runner.os == 'Linux'
+      name: Style around ExtensionProps embedding
+      run: |
+        ! ag -B2 -A2 'type.[A-Z].+struct..\n.+ExtensionProps\n[^\n]' openapi3/*.go
+
+    - if: runner.os == 'Linux'
+      name: Ensure all exported fields are mentioned in Validate() impls
+      run: |
+        for ty in $TYPES; do
+          # Ensure definition
+          if ! ag 'type.[A-Z].+struct..\n.+ExtensionProps' openapi3/*.go | grep -F "type $ty struct"; then
+            echo "OAI type $ty is not defined" && exit 1
+          fi
+
+          # Ensure impl Validate()
+          if ! git grep -InE 'func [(].+Schema[)] Validate[(]ctx context.Context[)].+error.+[{]'; then
+            echo "OAI type $ty does not implement Validate()" && exit 1
+          fi
+
+          # TODO: $ty mention all its exported fields within Validate()
+        done
+      env:
+        TYPES: >
+          Components
+          Contact
+          Discriminator
+          Encoding
+          Example
+          ExternalDocs
+          Info
+          License
+          Link
+          MediaType
+          OAuthFlow
+          OAuthFlows
+          Operation
+          Parameter
+          PathItem
+          RequestBody
+          Response
+          Schema
+          SecurityScheme
+          Server
+          ServerVariable
+          T
+          Tag
+          XML

README.md

@@ -6,7 +6,7 @@
 # Introduction
 A [Go](https://golang.org) project for handling [OpenAPI](https://www.openapis.org/) files. We target the latest OpenAPI version (currently 3), but the project contains support for older OpenAPI versions too.
 
-Licensed under the [MIT License](LICENSE).
+Licensed under the [MIT License](./LICENSE).
 
 ## Contributors and users
 The project has received pull requests from many people. Thanks to everyone!
@@ -27,7 +27,8 @@ Here's some projects that depend on _kin-openapi_:
 * [go-openapi](https://github.com/go-openapi)'s [spec3](https://github.com/go-openapi/spec3)
 	* an iteration on [spec](https://github.com/go-openapi/spec) (for OpenAPIv2)
 	* see [README](https://github.com/go-openapi/spec3/tree/3fab9faa9094e06ebd19ded7ea96d156c2283dca#oai-object-model---) for the missing parts
-* See [https://github.com/OAI](https://github.com/OAI)'s [great tooling list](https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md)
+
+Be sure to check [OpenAPI Initiative](https://github.com/OAI)'s [great tooling list](https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md) as well as [OpenAPI.Tools](https://openapi.tools/).
 
 # Structure
   * _openapi2_ ([godoc](https://godoc.org/github.com/getkin/kin-openapi/openapi2))

jsoninfo/marshal_ref.go

@@ -5,7 +5,7 @@ import (
 )
 
 func MarshalRef(value string, otherwise interface{}) ([]byte, error) {
-	if len(value) > 0 {
+	if value != "" {
 		return json.Marshal(&refProps{
 			Ref: value,
 		})
@@ -17,7 +17,7 @@ func UnmarshalRef(data []byte, destRef *string, destOtherwise interface{}) error
 	refProps := &refProps{}
 	if err := json.Unmarshal(data, refProps); err == nil {
 		ref := refProps.Ref
-		if len(ref) > 0 {
+		if ref != "" {
 			*destRef = ref
 			return nil
 		}
@@ -26,5 +26,5 @@ func UnmarshalRef(data []byte, destRef *string, destOtherwise interface{}) error
 }
 
 type refProps struct {
-	Ref string `json:"$ref,omitempty"`
+	Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty"`
 }

openapi3/callback.go

@@ -23,7 +23,8 @@ func (c Callbacks) JSONLookup(token string) (interface{}, error) {
 	return ref.Value, nil
 }
 
-// Callback is specified by OpenAPI/Swagger standard version 3.0.
+// Callback is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callbackObject
 type Callback map[string]*PathItem
 
 func (value Callback) Validate(ctx context.Context) error {

openapi3/components.go

@@ -8,9 +8,11 @@ import (
 	"github.com/getkin/kin-openapi/jsoninfo"
 )
 
-// Components is specified by OpenAPI/Swagger standard version 3.0.
+// Components is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject
 type Components struct {
 	ExtensionProps
+
 	Schemas         Schemas         `json:"schemas,omitempty" yaml:"schemas,omitempty"`
 	Parameters      ParametersMap   `json:"parameters,omitempty" yaml:"parameters,omitempty"`
 	Headers         Headers         `json:"headers,omitempty" yaml:"headers,omitempty"`

openapi3/discriminator.go

@@ -6,9 +6,11 @@ import (
 	"github.com/getkin/kin-openapi/jsoninfo"
 )
 
-// Discriminator is specified by OpenAPI/Swagger standard version 3.0.
+// Discriminator is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#discriminatorObject
 type Discriminator struct {
 	ExtensionProps
+
 	PropertyName string            `json:"propertyName" yaml:"propertyName"`
 	Mapping      map[string]string `json:"mapping,omitempty" yaml:"mapping,omitempty"`
 }

openapi3/encoding.go

@@ -8,6 +8,7 @@ import (
 )
 
 // Encoding is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#encodingObject
 type Encoding struct {
 	ExtensionProps
 

openapi3/examples.go → openapi3/example.go

@@ -25,6 +25,7 @@ func (e Examples) JSONLookup(token string) (interface{}, error) {
 }
 
 // Example is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#exampleObject
 type Example struct {
 	ExtensionProps
 

openapi3/external_docs.go

@@ -9,12 +9,13 @@ import (
 	"github.com/getkin/kin-openapi/jsoninfo"
 )
 
-// ExternalDocs is specified by OpenAPI/Swagger standard version 3.0.
+// ExternalDocs is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#external-documentation-object
 type ExternalDocs struct {
 	ExtensionProps
 
-	Description string `json:"description,omitempty"`
-	URL         string `json:"url,omitempty"`
+	Description string `json:"description,omitempty" yaml:"description,omitempty"`
+	URL         string `json:"url,omitempty" yaml:"url,omitempty"`
 }
 
 func (e *ExternalDocs) MarshalJSON() ([]byte, error) {

openapi3/header.go

@@ -26,7 +26,7 @@ func (h Headers) JSONLookup(token string) (interface{}, error) {
 }
 
 // Header is specified by OpenAPI/Swagger 3.0 standard.
-// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#headerObject
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#headerObject
 type Header struct {
 	Parameter
 }

openapi3/info.go

@@ -7,9 +7,11 @@ import (
 	"github.com/getkin/kin-openapi/jsoninfo"
 )
 
-// Info is specified by OpenAPI/Swagger standard version 3.0.
+// Info is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#infoObject
 type Info struct {
 	ExtensionProps
+
 	Title          string   `json:"title" yaml:"title"` // Required
 	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
 	TermsOfService string   `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
@@ -50,9 +52,11 @@ func (value *Info) Validate(ctx context.Context) error {
 	return nil
 }
 
-// Contact is specified by OpenAPI/Swagger standard version 3.0.
+// Contact is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#contactObject
 type Contact struct {
 	ExtensionProps
+
 	Name  string `json:"name,omitempty" yaml:"name,omitempty"`
 	URL   string `json:"url,omitempty" yaml:"url,omitempty"`
 	Email string `json:"email,omitempty" yaml:"email,omitempty"`
@@ -70,9 +74,11 @@ func (value *Contact) Validate(ctx context.Context) error {
 	return nil
 }
 
-// License is specified by OpenAPI/Swagger standard version 3.0.
+// License is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#licenseObject
 type License struct {
 	ExtensionProps
+
 	Name string `json:"name" yaml:"name"` // Required
 	URL  string `json:"url,omitempty" yaml:"url,omitempty"`
 }

openapi3/link.go

@@ -25,11 +25,13 @@ func (l Links) JSONLookup(token string) (interface{}, error) {
 
 var _ jsonpointer.JSONPointable = (*Links)(nil)
 
-// Link is specified by OpenAPI/Swagger standard version 3.0.
+// Link is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#linkObject
 type Link struct {
 	ExtensionProps
-	OperationID  string                 `json:"operationId,omitempty" yaml:"operationId,omitempty"`
+
 	OperationRef string                 `json:"operationRef,omitempty" yaml:"operationRef,omitempty"`
+	OperationID  string                 `json:"operationId,omitempty" yaml:"operationId,omitempty"`
 	Description  string                 `json:"description,omitempty" yaml:"description,omitempty"`
 	Parameters   map[string]interface{} `json:"parameters,omitempty" yaml:"parameters,omitempty"`
 	Server       *Server                `json:"server,omitempty" yaml:"server,omitempty"`

openapi3/media_type.go

@@ -8,6 +8,7 @@ import (
 )
 
 // MediaType is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject
 type MediaType struct {
 	ExtensionProps
 

openapi3/openapi3.go

@@ -9,8 +9,10 @@ import (
 )
 
 // T is the root of an OpenAPI v3 document
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oasObject
 type T struct {
 	ExtensionProps
+
 	OpenAPI      string               `json:"openapi" yaml:"openapi"` // Required
 	Components   Components           `json:"components,omitempty" yaml:"components,omitempty"`
 	Info         *Info                `json:"info" yaml:"info"`   // Required

openapi3/operation.go

@@ -11,6 +11,7 @@ import (
 )
 
 // Operation represents "operation" specified by" OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object
 type Operation struct {
 	ExtensionProps
 

openapi3/parameter.go

@@ -83,9 +83,10 @@ func (value Parameters) Validate(ctx context.Context) error {
 }
 
 // Parameter is specified by OpenAPI/Swagger 3.0 standard.
-// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameterObject
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject
 type Parameter struct {
 	ExtensionProps
+
 	Name            string      `json:"name,omitempty" yaml:"name,omitempty"`
 	In              string      `json:"in,omitempty" yaml:"in,omitempty"`
 	Description     string      `json:"description,omitempty" yaml:"description,omitempty"`

openapi3/path_item.go

@@ -8,8 +8,11 @@ import (
 	"github.com/getkin/kin-openapi/jsoninfo"
 )
 
+// PathItem is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject
 type PathItem struct {
 	ExtensionProps
+
 	Ref         string     `json:"$ref,omitempty" yaml:"$ref,omitempty"`
 	Summary     string     `json:"summary,omitempty" yaml:"summary,omitempty"`
 	Description string     `json:"description,omitempty" yaml:"description,omitempty"`

openapi3/paths.go

@@ -6,7 +6,8 @@ import (
 	"strings"
 )
 
-// Paths is specified by OpenAPI/Swagger standard version 3.0.
+// Paths is specified by OpenAPI/Swagger standard version 3.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#paths-object
 type Paths map[string]*PathItem
 
 func (value Paths) Validate(ctx context.Context) error {

openapi3/refs.go

@@ -8,6 +8,7 @@ import (
 )
 
 // Ref is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject
 type Ref struct {
 	Ref string `json:"$ref" yaml:"$ref"`
 }

openapi3/request_body.go

@@ -26,8 +26,10 @@ func (r RequestBodies) JSONLookup(token string) (interface{}, error) {
 }
 
 // RequestBody is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#requestBodyObject
 type RequestBody struct {
 	ExtensionProps
+
 	Description string  `json:"description,omitempty" yaml:"description,omitempty"`
 	Required    bool    `json:"required,omitempty" yaml:"required,omitempty"`
 	Content     Content `json:"content" yaml:"content"`

openapi3/response.go

@@ -11,6 +11,7 @@ import (
 )
 
 // Responses is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responsesObject
 type Responses map[string]*ResponseRef
 
 var _ jsonpointer.JSONPointable = (*Responses)(nil)
@@ -54,8 +55,10 @@ func (responses Responses) JSONLookup(token string) (interface{}, error) {
 }
 
 // Response is specified by OpenAPI/Swagger 3.0 standard.
+// See https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responseObject
 type Response struct {
 	ExtensionProps
+
 	Description *string `json:"description,omitempty" yaml:"description,omitempty"`
 	Headers     Headers `json:"headers,omitempty" yaml:"headers,omitempty"`
 	Content     Content `json:"content,omitempty" yaml:"content,omitempty"`
@@ -104,19 +107,15 @@ func (value *Response) Validate(ctx context.Context) error {
 			return err
 		}
 	}
-	if headers := value.Headers; headers != nil {
-		for _, header := range headers {
-			if err := header.Validate(ctx); err != nil {
-				return err
-			}
+	for _, header := range value.Headers {
+		if err := header.Validate(ctx); err != nil {
+			return err
 		}
 	}
 
-	if links := value.Links; links != nil {
-		for _, link := range links {
-			if err := link.Validate(ctx); err != nil {
-				return err
-			}
+	for _, link := range value.Links {
+		if err := link.Validate(ctx); err != nil {
+			return err
 		}
 	}
 	return nil