diff --git a/examples/v2.0/json/petstore-expanded.json b/examples/v2.0/json/petstore-expanded.json index 792c31eee3..e2395255fc 100644 --- a/examples/v2.0/json/petstore-expanded.json +++ b/examples/v2.0/json/petstore-expanded.json @@ -4,18 +4,18 @@ "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://helloreverb.com/terms/", + "termsOfService": "http://swagger.io/terms/", "contact": { - "name": "Wordnik API Team", - "email": "foo@example.com", - "url": "http://madskristensen.net" + "name": "Swagger API Team", + "email": "apiteam@swagger.io", + "url": "http://swagger.io" }, "license": { "name": "MIT", "url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT" } }, - "host": "petstore.swagger.wordnik.com", + "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" @@ -64,14 +64,14 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -89,7 +89,7 @@ "description": "Pet to add to the store", "required": true, "schema": { - "$ref": "#/definitions/newPet" + "$ref": "#/definitions/NewPet" } } ], @@ -97,13 +97,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -133,13 +133,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -164,7 +164,7 @@ "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -172,7 +172,7 @@ } }, "definitions": { - "pet": { + "Pet": { "required": [ "id", "name" @@ -190,10 +190,10 @@ } } }, - "newPet": { + "NewPet": { "allOf": [ { - "$ref": "pet" + "$ref": "#/definitions/Pet" }, { "required": [ @@ -208,7 +208,7 @@ } ] }, - "errorModel": { + "ErrorModel": { "required": [ "code", "message" diff --git a/examples/v2.0/json/petstore-minimal.json b/examples/v2.0/json/petstore-minimal.json index 317ace81eb..971134c5a6 100644 --- a/examples/v2.0/json/petstore-minimal.json +++ b/examples/v2.0/json/petstore-minimal.json @@ -4,15 +4,15 @@ "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://helloreverb.com/terms/", + "termsOfService": "http://swagger.io/terms/", "contact": { - "name": "Wordnik API Team" + "name": "Swagger API Team" }, "license": { "name": "MIT" } }, - "host": "petstore.swagger.wordnik.com", + "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" @@ -36,7 +36,7 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } } } @@ -45,7 +45,7 @@ } }, "definitions": { - "pet": { + "Pet": { "required": [ "id", "name" diff --git a/examples/v2.0/json/petstore-simple.json b/examples/v2.0/json/petstore-simple.json index 0e44295aac..c2ffaf6615 100644 --- a/examples/v2.0/json/petstore-simple.json +++ b/examples/v2.0/json/petstore-simple.json @@ -4,15 +4,15 @@ "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://helloreverb.com/terms/", + "termsOfService": "http://swagger.io/terms/", "contact": { - "name": "Wordnik API Team" + "name": "Swagger API Team" }, "license": { "name": "MIT" } }, - "host": "petstore.swagger.wordnik.com", + "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" @@ -61,14 +61,14 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -86,7 +86,7 @@ "description": "Pet to add to the store", "required": true, "schema": { - "$ref": "#/definitions/petInput" + "$ref": "#/definitions/PetInput" } } ], @@ -94,13 +94,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -130,13 +130,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -161,7 +161,7 @@ "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -169,7 +169,7 @@ } }, "definitions": { - "pet": { + "Pet": { "required": [ "id", "name" @@ -187,10 +187,10 @@ } } }, - "petInput": { + "PetInput": { "allOf": [ { - "$ref": "pet" + "$ref": "#/definitions/Pet" }, { "required": [ @@ -205,7 +205,7 @@ } ] }, - "errorModel": { + "ErrorModel": { "required": [ "code", "message" diff --git a/examples/v2.0/json/petstore-with-external-docs.json b/examples/v2.0/json/petstore-with-external-docs.json index b2105e76dc..ac609dc79e 100644 --- a/examples/v2.0/json/petstore-with-external-docs.json +++ b/examples/v2.0/json/petstore-with-external-docs.json @@ -4,11 +4,11 @@ "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://helloreverb.com/terms/", + "termsOfService": "http://swagger.io/terms/", "contact": { - "name": "Wordnik API Team", - "email": "foo@example.com", - "url": "http://madskristensen.net" + "name": "Swagger API Team", + "email": "apiteam@swagger.io", + "url": "http://swagger.io" }, "license": { "name": "MIT", @@ -17,9 +17,9 @@ }, "externalDocs": { "description": "find more info here", - "url": "https://helloreverb.com/about" + "url": "https://swagger.io/about" }, - "host": "petstore.swagger.wordnik.com", + "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" @@ -37,7 +37,7 @@ "operationId": "findPets", "externalDocs": { "description": "find more info here", - "url": "https://helloreverb.com/about" + "url": "https://swagger.io/about" }, "produces": [ "application/json", @@ -72,14 +72,14 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -97,7 +97,7 @@ "description": "Pet to add to the store", "required": true, "schema": { - "$ref": "#/definitions/newPet" + "$ref": "#/definitions/NewPet" } } ], @@ -105,13 +105,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -141,13 +141,13 @@ "200": { "description": "pet response", "schema": { - "$ref": "#/definitions/pet" + "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -172,7 +172,7 @@ "default": { "description": "unexpected error", "schema": { - "$ref": "#/definitions/errorModel" + "$ref": "#/definitions/ErrorModel" } } } @@ -180,14 +180,14 @@ } }, "definitions": { - "pet": { + "Pet": { "required": [ "id", "name" ], "externalDocs": { "description": "find more info here", - "url": "https://helloreverb.com/about" + "url": "https://swagger.io/about" }, "properties": { "id": { @@ -202,10 +202,10 @@ } } }, - "newPet": { + "NewPet": { "allOf": [ { - "$ref": "pet" + "$ref": "#/definitions/Pet" }, { "required": [ @@ -220,7 +220,7 @@ } ] }, - "errorModel": { + "ErrorModel": { "required": [ "code", "message" diff --git a/examples/v2.0/json/petstore.json b/examples/v2.0/json/petstore.json index b1ab216098..e7e800ab2b 100644 --- a/examples/v2.0/json/petstore.json +++ b/examples/v2.0/json/petstore.json @@ -4,15 +4,15 @@ "version": "1.0.0", "title": "Swagger Petstore", "contact": { - "name": "wordnik api team", - "url": "http://developer.wordnik.com" + "name": "Swagger API Team", + "url": "http://swagger.io" }, "license": { "name": "Creative Commons 4.0 International", "url": "http://creativecommons.org/licenses/by/4.0/" } }, - "host": "petstore.swagger.wordnik.com", + "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" diff --git a/examples/v2.0/yaml/petstore-expanded.yaml b/examples/v2.0/yaml/petstore-expanded.yaml index fb26a6c2db..40f29f825d 100644 --- a/examples/v2.0/yaml/petstore-expanded.yaml +++ b/examples/v2.0/yaml/petstore-expanded.yaml @@ -125,8 +125,7 @@ definitions: type: string NewPet: allOf: - - Pet: - $ref: '#/definitions/Pet' + - $ref: '#/definitions/Pet' - required: - name properties: diff --git a/fixtures/v2.0/json/models/modelWithComposition.json b/fixtures/v2.0/json/models/modelWithComposition.json index 819d8b5684..3a01b0b1c8 100644 --- a/fixtures/v2.0/json/models/modelWithComposition.json +++ b/fixtures/v2.0/json/models/modelWithComposition.json @@ -1,20 +1,18 @@ { - "definitions": { - "Pet": { - "discriminator": "petType", - "properties": { - "name": { - "type": "string" - }, - "petType": { - "type": "string" - } + "Pet": { + "discriminator": "petType", + "properties": { + "name": { + "type": "string" }, - "required": [ - "name", - "petType" - ] - } + "petType": { + "type": "string" + } + }, + "required": [ + "name", + "petType" + ] }, "Cat": { "description": "A representation of a cat", diff --git a/fixtures/v2.0/json/models/modelWithExamples.json b/fixtures/v2.0/json/models/modelWithExamples.json index f62be6624d..147bd5757f 100644 --- a/fixtures/v2.0/json/models/modelWithExamples.json +++ b/fixtures/v2.0/json/models/modelWithExamples.json @@ -1,28 +1,30 @@ { - "definitions": { - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] + "Pet": { + "properties": { + "name": { + "type": "string" + } }, - "Dog": { - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } + "required": [ + "name" + ] + }, + "Dog": { + "properties": { + "id": { + "type": "integer", + "format": "int64" }, - "required": [ - "name" - ] + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "example": { + "name": "Puma", + "id": 1 } } } \ No newline at end of file diff --git a/fixtures/v2.0/json/models/models.json b/fixtures/v2.0/json/models/models.json index 7eff6dbe04..2d47051e21 100644 --- a/fixtures/v2.0/json/models/models.json +++ b/fixtures/v2.0/json/models/models.json @@ -1,14 +1,12 @@ { - "definitions": { - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - } + "Pet": { + "properties": { + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] } } \ No newline at end of file diff --git a/fixtures/v2.0/json/models/multipleModels.json b/fixtures/v2.0/json/models/multipleModels.json index f62be6624d..f62438ea87 100644 --- a/fixtures/v2.0/json/models/multipleModels.json +++ b/fixtures/v2.0/json/models/multipleModels.json @@ -1,28 +1,26 @@ { - "definitions": { - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] + "Pet": { + "properties": { + "name": { + "type": "string" + } }, - "Dog": { - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } + "required": [ + "name" + ] + }, + "Dog": { + "properties": { + "id": { + "type": "integer", + "format": "int64" }, - "required": [ - "name" - ] - } + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] } } \ No newline at end of file diff --git a/schemas/v2.0/schema.json b/schemas/v2.0/schema.json index 2eedf5657b..1ae668e277 100644 --- a/schemas/v2.0/schema.json +++ b/schemas/v2.0/schema.json @@ -214,7 +214,6 @@ }, "mimeType": { "type": "string", - "pattern": "^[\\sa-z0-9\\-+;\\.=\\/]+$", "description": "The MIME type of the HTTP message." }, "operation": { @@ -605,6 +604,11 @@ "type": "string", "description": "The name of the parameter." }, + "allowEmptyValue": { + "type": "boolean", + "default": false, + "description": "allows sending a parameter by name only or with an empty value." + }, "type": { "type": "string", "enum": [ @@ -693,6 +697,11 @@ "type": "string", "description": "The name of the parameter." }, + "allowEmptyValue": { + "type": "boolean", + "default": false, + "description": "allows sending a parameter by name only or with an empty value." + }, "type": { "type": "string", "enum": [ @@ -945,6 +954,9 @@ "enum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/enum" }, + "additionalProperties": { + "$ref": "http://json-schema.org/draft-04/schema#/properties/additionalProperties" + }, "type": { "$ref": "http://json-schema.org/draft-04/schema#/properties/type" }, @@ -991,7 +1003,8 @@ "$ref": "#/definitions/externalDocs" }, "example": {} - } + }, + "additionalProperties": false }, "primitivesItems": { "type": "object", @@ -1376,7 +1389,6 @@ "parametersList": { "type": "array", "description": "The parameters needed to send a valid API call.", - "minItems": 1, "additionalItems": false, "items": { "oneOf": [ diff --git a/src/test/scala/ModelsTest.scala b/src/test/scala/ModelsTest.scala index 2f2016a0f3..9b505d6e47 100644 --- a/src/test/scala/ModelsTest.scala +++ b/src/test/scala/ModelsTest.scala @@ -15,7 +15,7 @@ import org.scalatest.matchers.ShouldMatchers class ModelsTest extends FlatSpec with ShouldMatchers with TestBase { val schema = readSchema(true) val factory = JsonSchemaFactory.byDefault() - val jsonSchema = factory.getJsonSchema(schema.get("definitions").get("schema")) + val jsonSchema = factory.getJsonSchema(schema.get("definitions").get("definitions")) it should "validate a models hash" in { val json = Source.fromFile("fixtures/v2.0/json/models/models.json").mkString diff --git a/versions/2.0.md b/versions/2.0.md index ed68090419..af96029616 100755 --- a/versions/2.0.md +++ b/versions/2.0.md @@ -78,7 +78,7 @@ Primitive data types in the Swagger Specification are based on the types support An additional primitive data type `"file"` is used by the [Parameter Object](#parameterObject) and the [Response Object](#responseObject) to set the parameter type or the response as being a file. -Primitives have an optional modifier property `format`. Swagger uses several known formats to more finely define the data type being used. However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. The formats defined by the Swagger Specification are: +Primitives have an optional modifier property `format`. Swagger uses several known formats to more finely define the data type being used. However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. Types that are not accompanied by a `format` property follow their definition from the JSON Schema (except for `file` type which is defined above). The formats defined by the Swagger Specification are: Common Name | [`type`](#dataTypeType) | [`format`](#dataTypeFormat) | Comments @@ -92,6 +92,7 @@ byte | `string` | `byte` | boolean | `boolean` | | date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) +password | `string` | `password` | Used to hint UIs the input needs to be obscured. ### Schema @@ -567,6 +568,7 @@ Field Name | Type | Description ---|:---:|--- type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"file"`. If `type` is `"file"`, the [`consumes`](#operationConsumes) MUST be either `"multipart/form-data"` or `" application/x-www-form-urlencoded"` and the parameter MUST be [`in`](#parameterIn) `"formData"`. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. +allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for either `query` or `formData` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are: Default value is `csv`. default | * | Sets a default value to the parameter. The type of the value depends on the defined [`type`](#parameterType). See http://json-schema.org/latest/json-schema-validation.html#anchor101. @@ -1105,6 +1107,8 @@ description: Pets operations A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse. +The Reference Object is a [JSON Reference](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. For this specification, only [canonical dereferencing](http://json-schema.org/latest/json-schema-core.html#anchor27) is supported. + ##### Fixed Fields Field Name | Type | Description ---|:---:|--- @@ -1126,8 +1130,10 @@ $ref: '#/definitions/Pet' The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the [JSON Schema Specification Draft 4](http://json-schema.org/) and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation. +Further information about the properties can be found in [JSON Schema Core](http://json-schema.org/latest/json-schema-core.html) and [JSON Schema Validation](http://json-schema.org/latest/json-schema-validation.html). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. + The following properties are taken directly from the JSON Schema definition and follow the same specifications: -- $ref +- $ref - As a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) - format (See [Data Type Formats](#dataTypeFormat) for further details) - title - description ([GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation) @@ -1153,6 +1159,7 @@ The following properties are taken from the JSON Schema definition but their def - items - allOf - properties +- additionalProperties Other than the JSON Schema subset fields, the following fields may be used for further schema documentation. @@ -1163,7 +1170,7 @@ Field Name | Type | Description readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as `readOnly` being `true` SHOULD NOT be in the `required` list of the defined schema. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. -example | Object | A free-form property to include a an example of an instance for this schema. +example | Any | A free-form property to include a an example of an instance for this schema. ###### Composition and Inheritance (Polymorphism)