diff --git a/go.mod b/go.mod index 3baa2aeaf..1644f5805 100644 --- a/go.mod +++ b/go.mod @@ -13,7 +13,7 @@ require ( github.com/go-openapi/swag v0.19.14 github.com/golang/protobuf v1.5.2 github.com/google/cel-go v0.9.0 - github.com/google/go-cmp v0.4.0 + github.com/google/go-cmp v0.5.5 github.com/google/gofuzz v1.1.0 github.com/google/uuid v1.1.2 github.com/googleapis/gnostic v0.5.1 @@ -26,7 +26,7 @@ require ( github.com/stretchr/testify v1.6.1 google.golang.org/genproto v0.0.0-20210831024726-fe130286e0e2 google.golang.org/protobuf v1.27.1 - gopkg.in/yaml.v2 v2.2.8 + gopkg.in/yaml.v2 v2.4.0 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b k8s.io/gengo v0.0.0-20210813121822-485abfe95c7c k8s.io/klog/v2 v2.2.0 diff --git a/go.sum b/go.sum index 280193867..36248f27f 100644 --- a/go.sum +++ b/go.sum @@ -19,6 +19,7 @@ github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDk github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc= github.com/cncf/udpa/go v0.0.0-20201120205902-5459f2c99403/go.mod h1:WmhPx2Nbnhtbo57+VJT5O0JRkEi1Wbu0z5j0R8u5Hbk= github.com/cncf/xds/go v0.0.0-20210312221358-fbca930ec8ed/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs= +github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -31,6 +32,9 @@ github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1m github.com/envoyproxy/go-control-plane v0.9.9-0.20201210154907-fd9021fe5dad/go.mod h1:cXg6YxExXjJnVBQHBLXeUAgxn2UodCpnH306RInaBQk= github.com/envoyproxy/go-control-plane v0.9.9-0.20210512163311-63b5d3c536b0/go.mod h1:hliV/p42l8fGbc6Y9bQ70uLwIvmJyVE5k4iMKlh8wCQ= github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c= +github.com/getkin/kin-openapi v0.76.0 h1:j77zg3Ec+k+r+GA3d8hBoXpAc6KX9TbBPrwQGBIy2sY= +github.com/getkin/kin-openapi v0.76.0/go.mod h1:660oXbgy5JFMKreazJaQTw7o+X00qeSyhcnluiMv+Xg= +github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk= github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04= github.com/go-logr/logr v0.1.0/go.mod h1:ixOQHD9gLJUVQQ2ZOR7zLEifBX6tGkNJF4QyIY7sIas= github.com/go-logr/logr v0.2.0 h1:QvGt2nLcHH0WK9orKa+ppBPAxREcH364nPUedEpK0TY= @@ -43,6 +47,8 @@ github.com/go-openapi/jsonreference v0.19.5/go.mod h1:RdybgQwPxbL4UEjuAruzK1x3nE github.com/go-openapi/spec v0.20.3 h1:uH9RQ6vdyPSs2pSy9fL8QPspDF2AMIMPtmK5coSSjtQ= github.com/go-openapi/spec v0.20.3/go.mod h1:gG4F8wdEDN+YPBMVnzE85Rbhf+Th2DTvA9nFPQ5AYEg= github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk= +github.com/go-openapi/swag v0.19.14 h1:gm3vOOXfiuw5i9p5N9xJvfjvuofpyvLA9Wr6QfK5Fng= +github.com/go-openapi/swag v0.19.14/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ= github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q= github.com/golang/glog v1.0.0/go.mod h1:EWib/APOK0SL3dFbYqvxE3UYd8E6s1ouQ7iEp/0LWV4= github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A= @@ -77,7 +83,10 @@ github.com/google/uuid v1.1.2 h1:EVhdT+1Kseyi1/pUmXKaFxYsDNy9RQYkMWRH68J/W7Y= github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/googleapis/gnostic v0.5.1 h1:A8Yhf6EtqTv9RMsU6MQTyrtV1TjWlR6xU9BsZIwuTCM= github.com/googleapis/gnostic v0.5.1/go.mod h1:6U4PtQXGIEt/Z3h5MAT7FNofLnw9vXk2cUuW7uA/OeU= +github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So= github.com/grpc-ecosystem/grpc-gateway v1.16.0/go.mod h1:BDjrQk3hbvj6Nolgz8mAMFbcEtjT1g+wF4CSlocrBnw= +github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY= +github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y= github.com/json-iterator/go v1.1.6 h1:MrUvLMLTMxbqFJ9kzlvat/rYZqZnW3u4wkLzWTaFwKs= github.com/json-iterator/go v1.1.6/go.mod h1:+SdeFBvtyEkXs7REEP0seUULqWtbJapLOCVDaaPEHmU= github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= @@ -145,6 +154,7 @@ golang.org/x/net v0.0.0-20190827160401-ba9fcec4b297/go.mod h1:z5CRVTTTmAJ677TzLL golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20200301022130-244492dfa37a/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20200822124328-c89045814202/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA= +golang.org/x/net v0.0.0-20210119194325-5f4716e94777/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM= golang.org/x/net v0.0.0-20210825183410-e898025ed96a h1:bRuuGXV8wwSdGTB+CtJf+FjgO1APK1CoO39T4BN/XBw= golang.org/x/net v0.0.0-20210825183410-e898025ed96a/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y= @@ -229,8 +239,11 @@ gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10= gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo= gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/pkg/common/common.go b/pkg/common/common.go index 6fcbc06aa..cf1d01f90 100644 --- a/pkg/common/common.go +++ b/pkg/common/common.go @@ -62,7 +62,6 @@ type PathHandlerByGroupVersion interface { HandlePrefix(path string, handler http.Handler) } - // Config is set of configuration for openAPI spec generation. type Config struct { // List of supported protocols such as https, http, etc. diff --git a/pkg/spec3/component.go b/pkg/spec3/component.go index c6fd27621..11f5d12a8 100644 --- a/pkg/spec3/component.go +++ b/pkg/spec3/component.go @@ -16,11 +16,14 @@ type Components struct { Responses map[string]*Response `json:"responses,omitempty"` // Parameters holds reusable Parameters Objects Parameters map[string]*Parameter `json:"parameters,omitempty"` - // the following fields are missing: - // examples Map[string, Example Object | Reference Object] - // requestBodies Map[string, Request Body Object | Reference Object] - // headers Map[string, Header Object | Reference Object] - // links Map[string, Link Object | Reference Object] + // Example holds reusable Example objects + Examples map[string]*Example `json:"examples,omitempty"` + // RequestBodies holds reusable Request Body objects + RequestBodies map[string]*RequestBody `json:"requestBodies,omitempty"` + // Links is a map of operations links that can be followed from the response + Links map[string]*Link `json:"links,omitempty"` + // Headers holds a maps of a headers name to its definition + Headers map[string]*Header `json:"headers,omitempty"` // callbacks Map[string, Callback Object | Reference Object] // // all fields are defined at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject diff --git a/pkg/spec3/example.go b/pkg/spec3/example.go new file mode 100644 index 000000000..0562cecae --- /dev/null +++ b/pkg/spec3/example.go @@ -0,0 +1,44 @@ +package spec3 + +import ( + "encoding/json" + + "github.com/go-openapi/spec" + "github.com/go-openapi/swag" +) + +// Example https://swagger.io/specification/#example-object + +type Example struct { + spec.Refable + ExampleProps + spec.VendorExtensible +} + +// MarshalJSON is a custom marshal function that knows how to encode RequestBody as JSON +func (e *Example) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(e.Refable) + if err != nil { + return nil, err + } + b2, err := json.Marshal(e.ExampleProps) + if err != nil { + return nil, err + } + b3, err := json.Marshal(e.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2, b3), nil +} + +type ExampleProps struct { + // Summary holds a short description of the example + Summary string `json:"summary,omitempty"` + // Description holds a long description of the example + Description string `json:"description,omitempty"` + // Embedded literal example. + Value interface{} `json:"value,omitempty"` + // A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. + ExternalValue string `json:"externalValue,omitempty"` +} diff --git a/pkg/spec3/header.go b/pkg/spec3/header.go new file mode 100644 index 000000000..346b2a16d --- /dev/null +++ b/pkg/spec3/header.go @@ -0,0 +1,73 @@ +package spec3 + +import ( + "encoding/json" + + "github.com/go-openapi/swag" + "k8s.io/kube-openapi/pkg/validation/spec" +) + +// Header a struct that describes a single operation parameter, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject +// +// Note that this struct is actually a thin wrapper around HeaderProps to make it referable and extensible +type Header struct { + spec.Refable + HeaderProps + spec.VendorExtensible +} + +// MarshalJSON is a custom marshal function that knows how to encode Header as JSON +func (h *Header) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(h.Refable) + if err != nil { + return nil, err + } + b2, err := json.Marshal(h.HeaderProps) + if err != nil { + return nil, err + } + b3, err := json.Marshal(h.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2, b3), nil +} + +func (h *Header) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &h.Refable); err != nil { + return err + } + if err := json.Unmarshal(data, &h.HeaderProps); err != nil { + return err + } + if err := json.Unmarshal(data, &h.VendorExtensible); err != nil { + return err + } + + return nil +} + +// HeaderProps a struct that describes a header object +type HeaderProps struct { + // Description holds a brief description of the parameter + Description string `json:"description,omitempty"` + // Required determines whether this parameter is mandatory + Required bool `json:"required,omitempty"` + // Deprecated declares this operation to be deprecated + Deprecated bool `json:"deprecated,omitempty"` + // AllowEmptyValue sets the ability to pass empty-valued parameters + AllowEmptyValue bool `json:"allowEmptyValue,omitempty"` + // Style describes how the parameter value will be serialized depending on the type of the parameter value + Style string `json:"style,omitempty"` + // Explode when true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map + Explode bool `json:"explode,omitempty"` + // AllowReserved determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 + AllowReserved bool `json:"allowReserved,omitempty"` + // Schema holds the schema defining the type used for the parameter + Schema *spec.Schema `json:"schema,omitempty"` + // Content holds a map containing the representations for the parameter + Content map[string]*MediaType `json:"content,omitempty"` + // the following fields are missing: + // TODO: Example field is missing - (example Any Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The example object is mutually exclusive of the examples object. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.) + // TODO: Examples field is missing - (examples Map[ string, Example Object | Reference Object] Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples object is mutually exclusive of the example object. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.) +} diff --git a/pkg/spec3/media_type.go b/pkg/spec3/media_type.go index 7947299f8..ba694ea74 100644 --- a/pkg/spec3/media_type.go +++ b/pkg/spec3/media_type.go @@ -8,7 +8,7 @@ import ( // MediaType a struct that allows you to specify content format, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#mediaTypeObject // -// Note that this struct is actually a thin wrapper around MediaTypeProps to make it referable and extensibl +// Note that this struct is actually a thin wrapper around MediaTypeProps to make it referable and extensible type MediaType struct { MediaTypeProps spec.VendorExtensible @@ -41,8 +41,51 @@ func (m *MediaType) UnmarshalJSON(data []byte) error { type MediaTypeProps struct { // Schema holds the schema defining the type used for the media type Schema *spec.Schema `json:"schema,omitempty"` - // the following fields are missing: - // TODO: Example field is missing - (example Any Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The example object is mutually exclusive of the examples object. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema.) - // TODO: Examples field is missing - (examples Map[ string, Example Object | Reference Object] Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The examples object is mutually exclusive of the example object. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.) - // TODO: Encoding field is missing - (encoding Map[string, Encoding Object] A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.) + // Example of the media type + Example interface{} `json:"example,omitempty"` + // Examples of the media type. Each example object should match the media type and specific schema if present + Examples map[string]*Example `json:"examples,omitempty"` + // A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded + Encoding map[string]*Encoding `json:"encoding,omitempty"` +} + +type Encoding struct { + EncodingProps + spec.VendorExtensible +} + +// MarshalJSON is a custom marshal function that knows how to encode Encoding as JSON +func (e *Encoding) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(e.EncodingProps) + if err != nil { + return nil, err + } + b2, err := json.Marshal(e.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2), nil +} + +func (e *Encoding) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &e.EncodingProps); err != nil { + return err + } + if err := json.Unmarshal(data, &e.VendorExtensible); err != nil { + return err + } + return nil +} + +type EncodingProps struct { + // Content Type for encoding a specific property + ContentType string `json:"contentType,omitempty"` + // A map allowing additional information to be provided as headers + Headers map[string]*Header `json:"headers,omitempty"` + // Describes how a specific property value will be serialized depending on its type + Style string `json:"style,omitempty"` + // When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect + Explode string `json:"explode,omitempty"` + // AllowReserved determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 + AllowReserved bool `json:"allowReserved,omitempty"` } diff --git a/pkg/spec3/parameter.go b/pkg/spec3/parameter.go index a5f7ce4f9..c873f25c5 100644 --- a/pkg/spec3/parameter.go +++ b/pkg/spec3/parameter.go @@ -33,6 +33,20 @@ func (p *Parameter) MarshalJSON() ([]byte, error) { return swag.ConcatJSON(b1, b2, b3), nil } +func (p *Parameter) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &p.Refable); err != nil { + return err + } + if err := json.Unmarshal(data, &p.ParameterProps); err != nil { + return err + } + if err := json.Unmarshal(data, &p.VendorExtensible); err != nil { + return err + } + + return nil +} + // ParameterProps a struct that describes a single operation parameter, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject type ParameterProps struct { // Name holds the name of the parameter @@ -57,7 +71,8 @@ type ParameterProps struct { Schema *spec.Schema `json:"schema,omitempty"` // Content holds a map containing the representations for the parameter Content map[string]*MediaType `json:"content,omitempty"` - // the following fields are missing: - // TODO: Example field is missing - (example Any Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The example object is mutually exclusive of the examples object. Furthermore, if referencing a schema which contains an example, the example value SHALL override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.) - // TODO: Examples field is missing - (examples Map[ string, Example Object | Reference Object] Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples object is mutually exclusive of the example object. Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.) + // Example of the parameter's potential value + Example interface{} `json:"example,omitempty"` + // Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding + Examples map[string]*Example `json:"examples,omitempty"` } diff --git a/pkg/spec3/path.go b/pkg/spec3/path.go index 9c939ed96..7f6f72e9b 100644 --- a/pkg/spec3/path.go +++ b/pkg/spec3/path.go @@ -108,7 +108,8 @@ type PathProps struct { Patch *Operation `json:"patch,omitempty"` // Trace defines TRACE operation Trace *Operation `json:"trace,omitempty"` - // TODO: Servers field is missing - (servers [Server Object] An alternative server array to service all operations in this path.) + // Servers is an alternative server array to service all operations in this path + Servers []*Server `json:"servers,omitempty"` // Parameters a list of parameters that are applicable for this operation Parameters []*Parameter `json:"parameters,omitempty"` } @@ -150,13 +151,14 @@ type OperationProps struct { Summary string `json:"summary,omitempty"` // Description holds a verbose explanation of the operation behavior Description string `json:"description,omitempty"` - // TODO: ExternalDocs field is missing - (externalDocs External Documentation Object Additional external documentation for this operation) + // ExternalDocs holds additional external documentation for this operation + ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"` // OperationId holds a unique string used to identify the operation OperationId string `json:"operationId,omitempty"` // Parameters a list of parameters that are applicable for this operation - // Parameters []*Parameter `json:"parameters,omitempty"` + Parameters []*Parameter `json:"parameters,omitempty"` // RequestBody holds the request body applicable for this operation - // RequestBody *RequestBody `json:"requestBody,omitempty"` + RequestBody *RequestBody `json:"requestBody,omitempty"` // Responses holds the list of possible responses as they are returned from executing this operation Responses *Responses `json:"responses,omitempty"` // TODO: Callbacks field is missing - (callbacks Map[string, Callback Object | Reference Object] A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. @@ -198,7 +200,6 @@ func (r *Responses) UnmarshalJSON(data []byte) error { return nil } - // ResponsesProps holds the list of possible responses as they are returned from executing this operation type ResponsesProps struct { // Default holds the documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses @@ -239,3 +240,112 @@ func (r *ResponsesProps) UnmarshalJSON(data []byte) error { } return nil } + +type ExternalDocumentation struct { + ExternalDocumentationProps + spec.VendorExtensible +} + +type ExternalDocumentationProps struct { + // Description is a short description of the target documentation. CommonMark syntax MAY be used for rich text representation. + Description string `json:"description,omitempty"` + // URL is the URL for the target documentation. + URL string `json:"url"` +} + +// MarshalJSON is a custom marshal function that knows how to encode Responses as JSON +func (e *ExternalDocumentation) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(e.ExternalDocumentationProps) + if err != nil { + return nil, err + } + b2, err := json.Marshal(e.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2), nil +} + +func (e *ExternalDocumentation) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &e.ExternalDocumentationProps); err != nil { + return err + } + if err := json.Unmarshal(data, &e.VendorExtensible); err != nil { + return err + } + return nil +} + +type Server struct { + ServerProps + spec.VendorExtensible +} + +type ServerProps struct { + // Description is a short description of the target documentation. CommonMark syntax MAY be used for rich text representation. + Description string `json:"description,omitempty"` + // URL is the URL for the target documentation. + URL string `json:"url"` + // Variables contains a map between a variable name and its value. The value is used for substitution in the server's URL templeate + Variables map[string]*ServerVariable `json:"variables,omitempty"` +} + +// MarshalJSON is a custom marshal function that knows how to encode Responses as JSON +func (s *Server) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(s.ServerProps) + if err != nil { + return nil, err + } + b2, err := json.Marshal(s.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2), nil +} + +func (s *Server) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &s.ServerProps); err != nil { + return err + } + if err := json.Unmarshal(data, &s.VendorExtensible); err != nil { + return err + } + return nil +} + +type ServerVariable struct { + ServerVariableProps + spec.VendorExtensible +} + +type ServerVariableProps struct { + // Enum is an enumeration of string values to be used if the substitution options are from a limited set + Enum []string `json:"enum,omitempty"` + // Default is the default value to use for substitution, which SHALL be sent if an alternate value is not supplied + Default string `json:"default"` + // Description is a description for the server variable + Description string `json:"description,omitempty"` +} + +// MarshalJSON is a custom marshal function that knows how to encode Responses as JSON +func (s *ServerVariable) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(s.ServerVariableProps) + if err != nil { + return nil, err + } + b2, err := json.Marshal(s.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2), nil +} + +func (s *ServerVariable) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &s.ServerVariableProps); err != nil { + return err + } + if err := json.Unmarshal(data, &s.VendorExtensible); err != nil { + return err + } + return nil +} diff --git a/pkg/spec3/response.go b/pkg/spec3/response.go index 55317d529..43658d4ea 100644 --- a/pkg/spec3/response.go +++ b/pkg/spec3/response.go @@ -52,9 +52,56 @@ type ResponseProps struct { // Description holds a short description of the response Description string `json:"description,omitempty"` // Headers holds a maps of a headers name to its definition - // Headers map[string]*Header `json:"headers,omitempty"` + Headers map[string]*Header `json:"headers,omitempty"` // Content holds a map containing descriptions of potential response payloads Content map[string]*MediaType `json:"content,omitempty"` - // the following fields are missing: - // TODO: Links field is missing - (links Map[string, Link Object | Reference Object] A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.) + // Links is a map of operations links that can be followed from the response + Links map[string]*Link `json:"links,omitempty"` +} + + +type Link struct { + spec.Refable + LinkProps + spec.VendorExtensible +} + +// MarshalJSON is a custom marshal function that knows how to encode Link as JSON +func (r *Link) MarshalJSON() ([]byte, error) { + b1, err := json.Marshal(r.Refable) + if err != nil { + return nil, err + } + b2, err := json.Marshal(r.LinkProps) + if err != nil { + return nil, err + } + b3, err := json.Marshal(r.VendorExtensible) + if err != nil { + return nil, err + } + return swag.ConcatJSON(b1, b2, b3), nil +} + +func (r *Link) UnmarshalJSON(data []byte) error { + if err := json.Unmarshal(data, &r.Refable); err != nil { + return err + } + if err := json.Unmarshal(data, &r.LinkProps); err != nil { + return err + } + if err := json.Unmarshal(data, &r.VendorExtensible); err != nil { + return err + } + + return nil +} + +// LinkProps describes a single response from an API Operation, more at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject +type LinkProps struct { + OperationId string `json:"operationId,omitempty"` + Parameters map[string]interface{} `json:"parameters,omitempty"` + Description string `json:"description,omitempty"` + RequestBody interface{} `json:"requestBody,omitempty"` + Server *Server `json:"server,omitempty"` } diff --git a/pkg/spec3/spec.go b/pkg/spec3/spec.go index 40009242a..df788eabf 100644 --- a/pkg/spec3/spec.go +++ b/pkg/spec3/spec.go @@ -11,13 +11,14 @@ import ( type OpenAPI struct { // Version represents the semantic version number of the OpenAPI Specification that this document uses Version string `json:"openapi"` - // Info provides metadata about the API Info *spec.Info `json:"info"` - // Paths holds the available target and operations for the API Paths *Paths `json:"paths,omitempty"` - + // Servers is an array of Server objects which provide connectivity information to a target server + Servers []*Server `json:"servers,omitempty"` // Components hold various schemas for the specification Components *Components `json:"components,omitempty"` + // ExternalDocs holds additional external documentation + ExternalDocs *ExternalDocumentation `json:"externalDocs,omitempty"` }