├── fixtures ├── v2.0 │ ├── yaml │ │ └── .gitkeep │ └── json │ │ ├── responses │ │ ├── negative │ │ │ ├── noResponses.json │ │ │ └── noResponsesWithVendorExtension.json │ │ ├── voidResponse.json │ │ ├── stringResponse.json │ │ ├── int32Response.json │ │ ├── int64Response.json │ │ ├── dateTimeResponse.json │ │ ├── stringArrayResponse.json │ │ ├── complexArrayResponse.json │ │ ├── stringResponseWithHeader.json │ │ └── multipleResponses.json │ │ ├── models │ │ ├── properties │ │ │ ├── simpleStringProperty.json │ │ │ ├── simpleByteProperty.json │ │ │ ├── simpleInt32Property.json │ │ │ ├── simpleInt64Property.json │ │ │ ├── simpleDateTimeProperty.json │ │ │ ├── propertyWithBooleanArray.json │ │ │ ├── propertyWithStringArray.json │ │ │ ├── simpleBooleanProperty.json │ │ │ ├── propertyWithComplexArray.json │ │ │ ├── propertyWithByteArray.json │ │ │ ├── propertyWithInt32Array.json │ │ │ ├── propertyWithInt64Array.json │ │ │ └── propertyWithDateTimeArray.json │ │ ├── modelWithInt64Map.json │ │ ├── modelWithStringProperty.json │ │ ├── modelWithDateTimeMap.json │ │ ├── modelWithInt32Map.json │ │ ├── models.json │ │ ├── modelWithArrayRef.json │ │ ├── modelWithPrimitiveArray.json │ │ ├── multipleModels.json │ │ ├── modelWithExamples.json │ │ ├── modelWithXmlAttributes.json │ │ ├── modelWithMultipleProperties.json │ │ └── modelWithComposition.json │ │ ├── general │ │ ├── negative │ │ │ ├── negativeExternalDocs.json │ │ │ └── negativeInfoObject.json │ │ ├── minimalInfoObject.json │ │ ├── externalDocs.json │ │ └── basicInfoObject.json │ │ └── resources │ │ ├── parameters │ │ ├── pathStringParameter.json │ │ ├── negative │ │ │ ├── pathFileParameter.json │ │ │ ├── queryFileParameter.json │ │ │ ├── bodyNonSchemaParameter.json │ │ │ ├── headerFileParameter.json │ │ │ ├── pathNonRequiredStringParameter.json │ │ │ ├── pathComplexParameter.json │ │ │ ├── queryComplexParameter.json │ │ │ ├── bodyFileParameter.json │ │ │ ├── headerComplexParameter.json │ │ │ ├── formDataComplexParameter.json │ │ │ ├── pathSchemaParameter.json │ │ │ ├── headerSchemaParameter.json │ │ │ ├── querySchemaParameter.json │ │ │ └── formDataSchemaParameter.json │ │ ├── formDataStringParameter.json │ │ ├── headerStringParameter.json │ │ ├── formDataInt64Parameter.json │ │ ├── pathInt64Parameter.json │ │ ├── bodyStringParameter.json │ │ ├── queryInt64Parameter.json │ │ ├── bodyComplexParameter.json │ │ ├── bodyInt64Parameter.json │ │ ├── formDataStringArrayParameter.json │ │ ├── pathStringArrayParameter.json │ │ ├── bodyComplexArrayParameter.json │ │ ├── bodyStringArrayParameter.json │ │ ├── headerStringArrayParameter.json │ │ ├── queryInt64ArrayParameter.json │ │ ├── headerInt64ArrayParameter.json │ │ └── bodyComplexInlineParameter.json │ │ ├── operations │ │ ├── operationWithTags.json │ │ ├── stringPathParamResource.json │ │ └── stringPathAndBoolQueryParamResource.json │ │ ├── resourceWithLinkedDefinitions_part1.json │ │ ├── resourceWithLinkedDefinitions.json │ │ ├── stringPathParamResource.json │ │ ├── cascadingSchemes.json │ │ ├── resourceWithRelativeHost.json │ │ ├── commonParameters.json │ │ ├── reusableParameters.json │ │ ├── vendorExtensionExamples.json │ │ ├── multipleMimeTypes.json │ │ ├── taggedResource.json │ │ └── resourceWithExamplePayload.json └── v1.2 │ └── helloworld │ ├── server │ ├── src │ │ └── main │ │ │ └── webapp │ │ │ ├── images │ │ │ ├── throbber.gif │ │ │ ├── logo_small.png │ │ │ ├── wordnik_api.png │ │ │ └── pet_store_api.png │ │ │ ├── api-docs │ │ │ ├── lib │ │ │ ├── jquery.slideto.min.js │ │ │ ├── jquery.wiggle.min.js │ │ │ └── jquery.ba-bbq.min.js │ │ │ ├── listings │ │ │ └── greetings │ │ │ ├── css │ │ │ └── highlight.default.css │ │ │ └── index.html │ ├── README.md │ └── pom.xml │ └── static │ ├── api-docs │ ├── README.md │ └── listings │ └── greetings ├── guidelines ├── EXTENSIONS.md └── v2.0 │ ├── README.md │ └── EXTENSIONS.md ├── .gitignore ├── examples ├── v2.0 │ ├── yaml │ │ ├── petstore-separate │ │ │ ├── common │ │ │ │ └── Error.yaml │ │ │ └── spec │ │ │ │ ├── NewPet.yaml │ │ │ │ ├── Pet.yaml │ │ │ │ ├── parameters.yaml │ │ │ │ └── swagger.yaml │ │ ├── petstore-minimal.yaml │ │ ├── petstore.yaml │ │ ├── petstore-expanded.yaml │ │ ├── petstore-simple.yaml │ │ ├── petstore-with-external-docs.yaml │ │ └── api-with-examples.yaml │ └── json │ │ ├── petstore-separate │ │ ├── common │ │ │ └── Error.json │ │ └── spec │ │ │ ├── Pet.json │ │ │ ├── NewPet.json │ │ │ ├── parameters.json │ │ │ └── swagger.json │ │ ├── petstore-minimal.json │ │ ├── petstore.json │ │ ├── api-with-examples.json │ │ ├── petstore-simple.json │ │ └── petstore-with-external-docs.json └── v3.0 │ ├── callback-example.yaml │ ├── petstore.yaml │ ├── petstore-expanded.yaml │ ├── link-example.yaml │ └── api-with-examples.yaml ├── schemas ├── v1.2 │ ├── README.md │ ├── resourceObject.json │ ├── resourceListing.json │ ├── infoObject.json │ ├── modelsObject.json │ ├── parameterObject.json │ ├── authorizationObject.json │ ├── apiDeclaration.json │ ├── oauth2GrantType.json │ ├── operationObject.json │ ├── dataTypeBase.json │ └── dataType.json └── v2.0 │ ├── bower.json │ ├── package.json │ └── README.md ├── MAINTAINERS.md ├── .travis.yml ├── CONTRIBUTORS.md ├── LICENSE ├── package.json ├── versions ├── smartapi-list.php └── mygene.info.v3.compliant ├── IMPLEMENTATIONS.md ├── DEVELOPMENT.md └── README.md /fixtures/v2.0/yaml/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/negative/noResponses.json: -------------------------------------------------------------------------------- 1 | { 2 | "x-test": {} 3 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/negative/noResponsesWithVendorExtension.json: -------------------------------------------------------------------------------- 1 | { 2 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/voidResponse.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "object created" 3 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleStringProperty.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "string" 3 | } 4 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/general/negative/negativeExternalDocs.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Find more info here" 3 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleByteProperty.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "string", 3 | "format": "byte" 4 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleInt32Property.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "integer", 3 | "format": "int32" 4 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleInt64Property.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "integer", 3 | "format": "int64" 4 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleDateTimeProperty.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "string", 3 | "format": "date-time" 4 | } -------------------------------------------------------------------------------- /guidelines/EXTENSIONS.md: -------------------------------------------------------------------------------- 1 | For OpenAPI Specification version 2.0, please see [v2.0/EXTENSIONS.md](v2.0/EXTENSIONS.md) 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | *.iml 3 | *.ipr 4 | *.iws 5 | target 6 | atlassian-ide-plugin.xml 7 | node_modules/ 8 | Gemfile.lock 9 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/general/minimalInfoObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "Swagger Sample App", 3 | "version": "1.0.1" 4 | } 5 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/general/externalDocs.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Find more info here", 3 | "url": "https://swagger.io" 4 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithBooleanArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "boolean" 5 | } 6 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithStringArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "string" 5 | } 6 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/simpleBooleanProperty.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "boolean", 3 | "description": "a boolean", 4 | "readOnly": true 5 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/stringResponse.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A simple string response", 3 | "schema": { 4 | "type": "string" 5 | } 6 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithComplexArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "$ref": "#/definitions/ComplexType" 5 | } 6 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithByteArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "string", 5 | "format": "byte" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithInt32Array.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "integer", 5 | "format": "int32" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithInt64Array.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "integer", 5 | "format": "int64" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithInt64Map.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "true", 3 | "additionalProperties": { 4 | "type": "integer", 5 | "format": "int64" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithStringProperty.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "true", 3 | "properties": { 4 | "name": { 5 | "type": "string" 6 | } 7 | } 8 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/properties/propertyWithDateTimeArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "array", 3 | "items": { 4 | "type": "string", 5 | "format": "date-time" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithDateTimeMap.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "true", 3 | "additionalProperties": { 4 | "type": "string", 5 | "format": "date-time" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/int32Response.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A simple string response", 3 | "schema": { 4 | "type": "integer", 5 | "format": "int32" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/int64Response.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A simple string response", 3 | "schema": { 4 | "type": "integer", 5 | "format": "int64" 6 | } 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/dateTimeResponse.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A date-time response", 3 | "schema": { 4 | "type": "string", 5 | "format": "date-time" 6 | } 7 | } -------------------------------------------------------------------------------- /guidelines/v2.0/README.md: -------------------------------------------------------------------------------- 1 | ## Guidelines for OpenAPI Definitions 2 | 3 | * [Reuse](REUSE.md) of OpenAPI definitions 4 | * [Extending](EXTENSIONS.md) OpenAPI definitions with custom metadata 5 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/images/throbber.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/HEAD/fixtures/v1.2/helloworld/server/src/main/webapp/images/throbber.gif -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/images/logo_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/HEAD/fixtures/v1.2/helloworld/server/src/main/webapp/images/logo_small.png -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/images/wordnik_api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/HEAD/fixtures/v1.2/helloworld/server/src/main/webapp/images/wordnik_api.png -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithInt32Map.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "This is a Map[String, Integer]", 3 | "additionalProperties": { 4 | "type": "integer", 5 | "format": "int32" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/pathStringParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "path", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "string" 7 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/images/pet_store_api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SmartAPI/smartAPI-Specification/HEAD/fixtures/v1.2/helloworld/server/src/main/webapp/images/pet_store_api.png -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/pathFileParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "path", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "file" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/queryFileParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "query", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "file" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/formDataStringParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "formData", 4 | "description": "users first name", 5 | "required": true, 6 | "type": "string" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/bodyNonSchemaParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "body", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "string" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/headerFileParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "header", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "file" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/stringArrayResponse.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A string array response", 3 | "schema": { 4 | "type": "array", 5 | "items": { 6 | "type": "string" 7 | } 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/headerStringParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "token", 3 | "in": "header", 4 | "description": "token to be passed as a header", 5 | "required": true, 6 | "type": "string" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/models.json: -------------------------------------------------------------------------------- 1 | { 2 | "Pet": { 3 | "properties": { 4 | "name": { 5 | "type": "string" 6 | } 7 | }, 8 | "required": [ 9 | "name" 10 | ] 11 | } 12 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/pathNonRequiredStringParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "path", 4 | "description": "username to fetch", 5 | "required": false, 6 | "type": "string" 7 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-separate/common/Error.yaml: -------------------------------------------------------------------------------- 1 | type: object 2 | required: 3 | - code 4 | - message 5 | properties: 6 | code: 7 | type: integer 8 | format: int32 9 | message: 10 | type: string 11 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/formDataInt64Parameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "id", 3 | "in": "formData", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "integer", 7 | "format": "int64" 8 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/pathComplexParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "path", 4 | "description": "users first name", 5 | "required": true, 6 | "$ref": "#/definitions/Nothing" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/queryComplexParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "query", 4 | "description": "users first name", 5 | "required": true, 6 | "$ref": "#/definitions/Nothing" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/pathInt64Parameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "id", 3 | "in": "path", 4 | "description": "username to fetch", 5 | "required": true, 6 | "type": "integer", 7 | "format": "int64" 8 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyStringParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "body", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "schema": { 7 | "type": "string" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/bodyFileParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "username", 3 | "in": "body", 4 | "description": "username to fetch", 5 | "required": true, 6 | "schema": { 7 | "type": "file" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/headerComplexParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "header", 4 | "description": "users first name", 5 | "required": true, 6 | "$ref": "#/definitions/Nothing" 7 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/queryInt64Parameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "id", 3 | "in": "query", 4 | "description": "ID of the object to fetch", 5 | "required": true, 6 | "type": "integer", 7 | "format": "int64" 8 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/formDataComplexParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "formData", 4 | "description": "users first name", 5 | "required": true, 6 | "$ref": "#/definitions/Nothing" 7 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-separate/spec/NewPet.yaml: -------------------------------------------------------------------------------- 1 | type: object 2 | allOf: 3 | - $ref: 'Pet.yaml' 4 | - required: 5 | - name 6 | properties: 7 | description: 8 | type: integer 9 | format: int64 10 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/complexArrayResponse.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A complex object array response", 3 | "schema": { 4 | "type": "array", 5 | "items": { 6 | "$ref": "#/definitions/VeryComplexType" 7 | } 8 | } 9 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-separate/spec/Pet.yaml: -------------------------------------------------------------------------------- 1 | type: object 2 | required: 3 | - id 4 | - name 5 | properties: 6 | id: 7 | type: integer 8 | format: int64 9 | name: 10 | type: string 11 | tag: 12 | type: string 13 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyComplexParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "body", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "schema": { 7 | "$ref": "#/definitions/User" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyInt64Parameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "id", 3 | "in": "body", 4 | "description": "id to add", 5 | "required": true, 6 | "schema": { 7 | "type": "integer", 8 | "format": "int64" 9 | } 10 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/pathSchemaParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "path", 4 | "description": "users first name", 5 | "required": true, 6 | "schema": { 7 | "$ref": "#/definitions/Nothing" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/headerSchemaParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "header", 4 | "description": "users first name", 5 | "required": true, 6 | "schema": { 7 | "$ref": "#/definitions/Nothing" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/querySchemaParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "query", 4 | "description": "users first name", 5 | "required": true, 6 | "schema": { 7 | "$ref": "#/definitions/Nothing" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/static/api-docs: -------------------------------------------------------------------------------- 1 | { 2 | "swaggerVersion": "1.2", 3 | "apis": [ 4 | { 5 | "path": "http://localhost:8000/listings/greetings", 6 | "description": "Generating greetings in our application." 7 | } 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/negative/formDataSchemaParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "firstName", 3 | "in": "formData", 4 | "description": "users first name", 5 | "required": true, 6 | "schema": { 7 | "$ref": "#/definitions/Nothing" 8 | } 9 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/api-docs: -------------------------------------------------------------------------------- 1 | { 2 | "swaggerVersion": "1.2", 3 | "apis": [ 4 | { 5 | "path": "http://localhost:8000/listings/greetings", 6 | "description": "Generating greetings in our application." 7 | } 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/formDataStringArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "formData", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "type": "array", 7 | "items": { 8 | "type": "string" 9 | } 10 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/stringResponseWithHeader.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "A simple string response", 3 | "schema": { 4 | "type": "string" 5 | }, 6 | "headers": { 7 | "is-dog": {"type": "boolean"}, 8 | "is-cat": {"type": "boolean"} 9 | } 10 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/static/README.md: -------------------------------------------------------------------------------- 1 | # Static Hello World Sample Files 2 | 3 | This sample project provides the static files to be hosted in your web server, following the Hello World sample described in the [wiki](https://github.com/swagger-api/swagger-spec/wiki/Hello-World-Sample). 4 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/pathStringArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "usernames", 3 | "in": "path", 4 | "description": "usernames to pass", 5 | "required": true, 6 | "type": "array", 7 | "items": { 8 | "type": "string" 9 | }, 10 | "collectionFormat": "csv" 11 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyComplexArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "body", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "schema": { 7 | "type": "array", 8 | "items": { 9 | "type": "string" 10 | } 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyStringArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "body", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "schema": { 7 | "type": "array", 8 | "items": { 9 | "type": "string" 10 | } 11 | } 12 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/headerStringArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "token", 3 | "in": "header", 4 | "description": "token to be passed as a header", 5 | "required": true, 6 | "type": "array", 7 | "items": { 8 | "type": "string" 9 | }, 10 | "collectionFormat": "csv" 11 | } -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-separate/common/Error.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "required": [ 4 | "code", 5 | "message" 6 | ], 7 | "properties": { 8 | "code": { 9 | "type": "integer", 10 | "format": "int32" 11 | }, 12 | "message": { 13 | "type": "string" 14 | } 15 | } 16 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/queryInt64ArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "id", 3 | "in": "query", 4 | "description": "ID of the object to fetch", 5 | "required": true, 6 | "type": "array", 7 | "items": { 8 | "type": "integer", 9 | "format": "int64" 10 | }, 11 | "collectionFormat": "csv" 12 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/headerInt64ArrayParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "token", 3 | "in": "header", 4 | "description": "token to be passed as a header", 5 | "required": true, 6 | "type": "array", 7 | "items": { 8 | "type": "integer", 9 | "format": "int64" 10 | }, 11 | "collectionFormat": "csv" 12 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithArrayRef.json: -------------------------------------------------------------------------------- 1 | { 2 | "required": [ 3 | "id" 4 | ], 5 | "properties": { 6 | "id": { 7 | "type": "integer", 8 | "format": "int64" 9 | }, 10 | "children": { 11 | "type": "array", 12 | "items": { 13 | "$ref": "#/definitions/Person" 14 | } 15 | } 16 | } 17 | } -------------------------------------------------------------------------------- /schemas/v1.2/README.md: -------------------------------------------------------------------------------- 1 | # Swagger Specification JSON Schemas 2 | 3 | The work on the JSON Schema for the Swagger Specification was donated to the community by [Francis Galiegue](https://github.com/fge)! 4 | 5 | Keep in mind that due to some JSON Schema limitations, not all constraints can be described. The missing constraints will be listed here in the future. 6 | -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-separate/spec/Pet.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "required": [ 4 | "id", 5 | "name" 6 | ], 7 | "properties": { 8 | "id": { 9 | "type": "integer", 10 | "format": "int64" 11 | }, 12 | "name": { 13 | "type": "string" 14 | }, 15 | "tag": { 16 | "type": "string" 17 | } 18 | } 19 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithPrimitiveArray.json: -------------------------------------------------------------------------------- 1 | { 2 | "required": [ 3 | "id" 4 | ], 5 | "properties": { 6 | "id": { 7 | "type": "integer", 8 | "format": "int64" 9 | }, 10 | "childrensAges": { 11 | "type": "array", 12 | "items": { 13 | "type": "integer", 14 | "format": "int32" 15 | } 16 | } 17 | } 18 | } -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-separate/spec/NewPet.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "object", 3 | "allOf": [ 4 | { 5 | "$ref": "Pet.json" 6 | }, 7 | { 8 | "required": [ 9 | "name" 10 | ], 11 | "properties": { 12 | "description": { 13 | "type": "integer", 14 | "format": "int64" 15 | } 16 | } 17 | } 18 | ] 19 | } -------------------------------------------------------------------------------- /schemas/v2.0/bower.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "swagger-schema", 3 | "version": "2.0.0-96305d9", 4 | "homepage": "https://github.com/swagger-api/swagger-schema", 5 | "authors": [ 6 | "''" 7 | ], 8 | "main": "./schema.json", 9 | "description": "Swagger JSON Schema", 10 | "keywords": [ 11 | "swagger", 12 | "schema", 13 | "api" 14 | ], 15 | "license": "Apache-2.0" 16 | } 17 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/responses/multipleResponses.json: -------------------------------------------------------------------------------- 1 | { 2 | "200": { 3 | "description": "simple string response", 4 | "schema": { 5 | "type": "string" 6 | } 7 | }, 8 | "201": { 9 | "description": "object created" 10 | }, 11 | "default": { 12 | "description": "oops", 13 | "schema": { 14 | "type": "integer", 15 | "format": "int32" 16 | } 17 | } 18 | } -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | ## Active 2 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 5 | * Ron Ratovsky [@webron](https://github.com/webron) 6 | 7 | ## Emeritus 8 | * Jason Harmon [@jharmn](https://github.com/jharmn) 9 | * Tony Tam [@fehguy](https://github.com/fehguy) 10 | -------------------------------------------------------------------------------- /schemas/v2.0/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "swagger-schema-official", 3 | "version": "2.0.0-bab6bed", 4 | "description": "Swagger JSON Schema ", 5 | "scripts": { 6 | "test": "echo \"Error: no test specified\" && exit 1" 7 | }, 8 | "keywords": [ 9 | "swagger", 10 | "schema", 11 | "api" 12 | ], 13 | "author": "", 14 | "main": "./schema.json", 15 | "license": "Apache-2.0" 16 | } 17 | -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-separate/spec/parameters.yaml: -------------------------------------------------------------------------------- 1 | tagsParam: 2 | name: tags 3 | in: query 4 | description: tags to filter by 5 | required: false 6 | type: array 7 | collectionFormat: csv 8 | items: 9 | type: string 10 | limitsParam: 11 | name: limit 12 | in: query 13 | description: maximum number of results to return 14 | required: false 15 | type: integer 16 | format: int32 17 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/general/negative/negativeInfoObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "This is a sample server Petstore server.", 3 | "termsOfService": "http://swagger.io/terms/", 4 | "contact": { 5 | "name": "API Support", 6 | "url": "http://www.swagger.io/support", 7 | "email": "support@swagger.io" 8 | }, 9 | "license": { 10 | "url": "http://www.apache.org/licenses/LICENSE-2.0.html" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/lib/jquery.slideto.min.js: -------------------------------------------------------------------------------- 1 | (function(b){b.fn.slideto=function(a){a=b.extend({slide_duration:"slow",highlight_duration:3E3,highlight:true,highlight_color:"#FFFF99"},a);return this.each(function(){obj=b(this);b("body").animate({scrollTop:obj.offset().top},a.slide_duration,function(){a.highlight&&b.ui.version&&obj.effect("highlight",{color:a.highlight_color},a.highlight_duration)})})}})(jQuery); 2 | -------------------------------------------------------------------------------- /schemas/v1.2/resourceObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "path" ], 6 | "properties": { 7 | "path": { "type": "string", "format": "uri" }, 8 | "description": { "type": "string" } 9 | }, 10 | "additionalProperties": false 11 | } -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | script: 3 | - npm install 4 | env: 5 | - VALIDATORS=tv4 6 | - VALIDATORS=zschema 7 | matrix: 8 | allow_failures: 9 | - env: VALIDATORS=tv4 10 | install: 11 | - rm -rf ~/.nvm 12 | - curl -L https://raw.githubusercontent.com/creationix/nvm/master/install.sh | sh 13 | - source ~/.nvm/nvm.sh 14 | - nvm install 6.1 15 | - nvm use 6.1 16 | script: 17 | - npm install 18 | - node node_modules/mdv/mdv versions/3.*.md 19 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/multipleModels.json: -------------------------------------------------------------------------------- 1 | { 2 | "Pet": { 3 | "properties": { 4 | "name": { 5 | "type": "string" 6 | } 7 | }, 8 | "required": [ 9 | "name" 10 | ] 11 | }, 12 | "Dog": { 13 | "properties": { 14 | "id": { 15 | "type": "integer", 16 | "format": "int64" 17 | }, 18 | "name": { 19 | "type": "string" 20 | } 21 | }, 22 | "required": [ 23 | "name" 24 | ] 25 | } 26 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/general/basicInfoObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "Swagger Sample App", 3 | "description": "This is a sample server Petstore server.", 4 | "termsOfService": "http://swagger.io/terms/", 5 | "contact": { 6 | "name": "API Support", 7 | "url": "http://www.swagger.io/support", 8 | "email": "support@swagger.io" 9 | }, 10 | "license": { 11 | "name": "Apache 2.0", 12 | "url": "http://www.apache.org/licenses/LICENSE-2.0.html" 13 | }, 14 | "version": "1.0.1" 15 | } 16 | -------------------------------------------------------------------------------- /schemas/v2.0/README.md: -------------------------------------------------------------------------------- 1 | # Swagger Specification JSON Schemas 2 | 3 | This is only JSON Schema file for Swagger version 2.0. Download and Install it via NPM or Bower. 4 | 5 | ## Install via NPM 6 | 7 | ```shell 8 | npm install --save swagger-schema-official 9 | ``` 10 | 11 | #### Install 1.2 version via NPM 12 | 13 | ```shell 14 | npm install --save swagger-schema-official@1.2.0 15 | ``` 16 | ## Install via Bower 17 | 18 | ```shell 19 | bower install --save swagger-schema 20 | ``` 21 | 22 | ## License 23 | 24 | Apache-2.0 25 | -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-separate/spec/parameters.json: -------------------------------------------------------------------------------- 1 | { 2 | "tagsParam": { 3 | "name": "tags", 4 | "in": "query", 5 | "description": "tags to filter by", 6 | "required": false, 7 | "type": "array", 8 | "collectionFormat": "csv", 9 | "items": { 10 | "type": "string" 11 | } 12 | }, 13 | "limitsParam": { 14 | "name": "limit", 15 | "in": "query", 16 | "description": "maximum number of results to return", 17 | "required": false, 18 | "type": "integer", 19 | "format": "int32" 20 | } 21 | } -------------------------------------------------------------------------------- /CONTRIBUTORS.md: -------------------------------------------------------------------------------- 1 | * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) 2 | * Jason Harmon [@jharmn](https://github.com/jharmn) 3 | * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) 4 | * Kris Hahn [@KrisHahn](https://github.com/krishahn) 5 | * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) 6 | * Mike Ralphson [@MikeRalphson](https://github.com/mikeralphson) 7 | * Rob Dolin [@RobDolinMS](https://github.com/robdolinms) 8 | * Ron Ratovsky [@webron](https://github.com/webron) 9 | * Tony Tam [@fehguy](https://github.com/fehguy) 10 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithExamples.json: -------------------------------------------------------------------------------- 1 | { 2 | "Pet": { 3 | "properties": { 4 | "name": { 5 | "type": "string" 6 | } 7 | }, 8 | "required": [ 9 | "name" 10 | ] 11 | }, 12 | "Dog": { 13 | "properties": { 14 | "id": { 15 | "type": "integer", 16 | "format": "int64" 17 | }, 18 | "name": { 19 | "type": "string" 20 | } 21 | }, 22 | "required": [ 23 | "name" 24 | ], 25 | "example": { 26 | "name": "Puma", 27 | "id": 1 28 | } 29 | } 30 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/parameters/bodyComplexInlineParameter.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "user", 3 | "in": "body", 4 | "description": "user to add to the system", 5 | "required": true, 6 | "schema": { 7 | "type": "object", 8 | "required": [ "name", "id" ], 9 | "properties": { 10 | "id": { 11 | "type": "integer", 12 | "format": "int64" 13 | }, 14 | "name": { 15 | "type": "string" 16 | }, 17 | "keys": { 18 | "type": "array", 19 | "items": { 20 | "type": "integer" 21 | } 22 | } 23 | } 24 | } 25 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/README.md: -------------------------------------------------------------------------------- 1 | # All-in-one Static Hello World Sample 2 | 3 | This sample project provides an all-one-one package demo for the Hello World sample described in the [wiki](https://github.com/swagger-api/swagger-spec/wiki/Hello-World-Sample). 4 | 5 | ## Requirements 6 | 7 | This samples requires Java 5 or above and [Maven](http://maven.apache.org) installed. 8 | 9 | ## Run the sample 10 | 11 | In your favorite command-line, run: 12 | 13 | ``` 14 | mvn jetty:run 15 | ``` 16 | 17 | Then in your favorite web browser, open: 18 | ``` 19 | http://localhost:8000 20 | ``` 21 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithXmlAttributes.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "this model serves xml and json structures", 3 | "xml": { 4 | "name": "XMLModel" 5 | }, 6 | "properties": { 7 | "id": { 8 | "type": "integer", 9 | "format": "int64", 10 | "xml": { 11 | "attribute": true, 12 | "namespace": "ns1", 13 | "prefix": "urn1" 14 | } 15 | }, 16 | "items": { 17 | "type": "array", 18 | "items": { 19 | "type": "string" 20 | }, 21 | "xml": { 22 | "wrapped": true 23 | } 24 | } 25 | } 26 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2017 The Linux Foundation 2 | 3 | Licensed under the Apache License, Version 2.0 (the "License"); 4 | you may not use this file except in compliance with the License. 5 | You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) 6 | 7 | Unless required by applicable law or agreed to in writing, software 8 | distributed under the License is distributed on an "AS IS" BASIS, 9 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 10 | See the License for the specific language governing permissions and 11 | limitations under the License. 12 | -------------------------------------------------------------------------------- /schemas/v1.2/resourceListing.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceListing.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "swaggerVersion", "apis" ], 6 | "properties": { 7 | "swaggerVersion": { "enum": [ "1.2" ] }, 8 | "apis": { 9 | "type": "array", 10 | "items": { "$ref": "resourceObject.json#" } 11 | }, 12 | "apiVersion": { "type": "string" }, 13 | "info": { "$ref": "infoObject.json#" }, 14 | "authorizations": { "$ref": "authorizationObject.json#" } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /schemas/v1.2/infoObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/infoObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "info object (section 5.1.3)", 5 | "type": "object", 6 | "required": [ "title", "description" ], 7 | "properties": { 8 | "title": { "type": "string" }, 9 | "description": { "type": "string" }, 10 | "termsOfServiceUrl": { "type": "string", "format": "uri" }, 11 | "contact": { "type": "string", "format": "email" }, 12 | "license": { "type": "string" }, 13 | "licenseUrl": { "type": "string", "format": "uri" } 14 | }, 15 | "additionalProperties": false 16 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/static/listings/greetings: -------------------------------------------------------------------------------- 1 | { 2 | "swaggerVersion": "1.2", 3 | "basePath": "http://localhost:8000/greetings", 4 | "apis": [ 5 | { 6 | "path": "/hello/{subject}", 7 | "operations": [ 8 | { 9 | "method": "GET", 10 | "summary": "Greet our subject with hello!", 11 | "type": "string", 12 | "nickname": "helloSubject", 13 | "parameters": [ 14 | { 15 | "name": "subject", 16 | "description": "The subject to be greeted.", 17 | "required": true, 18 | "type": "string", 19 | "paramType": "path" 20 | } 21 | ] 22 | } 23 | ] 24 | } 25 | ] 26 | } 27 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/listings/greetings: -------------------------------------------------------------------------------- 1 | { 2 | "swaggerVersion": "1.2", 3 | "basePath": "http://localhost:8000/greetings", 4 | "apis": [ 5 | { 6 | "path": "/hello/{subject}", 7 | "operations": [ 8 | { 9 | "method": "GET", 10 | "summary": "Greet our subject with hello!", 11 | "type": "string", 12 | "nickname": "helloSubject", 13 | "parameters": [ 14 | { 15 | "name": "subject", 16 | "description": "The subject to be greeted.", 17 | "required": true, 18 | "type": "string", 19 | "paramType": "path" 20 | } 21 | ] 22 | } 23 | ] 24 | } 25 | ] 26 | } 27 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/lib/jquery.wiggle.min.js: -------------------------------------------------------------------------------- 1 | /* 2 | jQuery Wiggle 3 | Author: WonderGroup, Jordan Thomas 4 | URL: http://labs.wondergroup.com/demos/mini-ui/index.html 5 | License: MIT (http://en.wikipedia.org/wiki/MIT_License) 6 | */ 7 | jQuery.fn.wiggle=function(o){var d={speed:50,wiggles:3,travel:5,callback:null};var o=jQuery.extend(d,o);return this.each(function(){var cache=this;var wrap=jQuery(this).wrap('
').css("position","relative");var calls=0;for(i=1;i<=o.wiggles;i++){jQuery(this).animate({left:"-="+o.travel},o.speed).animate({left:"+="+o.travel*2},o.speed*2).animate({left:"-="+o.travel},o.speed,function(){calls++;if(jQuery(cache).parent().hasClass('wiggle-wrap')){jQuery(cache).parent().replaceWith(cache);} 8 | if(calls==o.wiggles&&jQuery.isFunction(o.callback)){o.callback();}});}});}; -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/operations/operationWithTags.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Returns a pet based on ID", 3 | "summary": "Find pet by ID", 4 | "operationId": "getPetsById", 5 | "tags": [ "foo", "bar"], 6 | "produces": [ 7 | "application/json", 8 | "text/html" 9 | ], 10 | "parameters": [ 11 | { 12 | "name": "petId", 13 | "in": "path", 14 | "description": "ID of pet that needs to be fetched", 15 | "required": true, 16 | "type": "integer", 17 | "format": "int64" 18 | } 19 | ], 20 | "responses": { 21 | "200": { 22 | "description": "a pet to be returned", 23 | "schema": {"$ref": "#/definitions/Pet"} 24 | }, 25 | "default": { 26 | "description": "Unexpected error", 27 | "schema": {"$ref": "#/definitions/ErrorModel"} 28 | } 29 | } 30 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "swagger-validator", 3 | "version": "0.0.1", 4 | "description": "validates a file", 5 | "author": { 6 | "name": "Tony Tam", 7 | "email": "fehguy@gmail.com", 8 | "url": "http://swagger.io" 9 | }, 10 | "license": "Apache", 11 | "readmeFilename": "README.md", 12 | "dependencies": { 13 | "tv4": "~1.1.x", 14 | "chai": "1.9.x" 15 | }, 16 | "devDependencies": { 17 | "glob": "^4.0.5", 18 | "gulp": "~3.8.x", 19 | "gulp-ext-replace": "^0.1.0", 20 | "gulp-jsonlint": "0.0.3", 21 | "gulp-util": "^3.0.0", 22 | "gulp-yaml": "0.0.3", 23 | "js-yaml": "^3.1.0", 24 | "json2yaml": "^1.0.3", 25 | "jsonschema": "^1.0.0", 26 | "map-stream": "^0.1.0", 27 | "mdv": "^1.0.3", 28 | "mocha": "^1.21.3", 29 | "q": "^1.0.1", 30 | "request": "^2.39.0", 31 | "z-schema": "^2.4.9" 32 | } 33 | } 34 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/operations/stringPathParamResource.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Returns a pet based on ID", 3 | "summary": "Find pet by ID", 4 | "operationId": "getPetsById", 5 | "produces": [ 6 | "application/json", 7 | "text/html" 8 | ], 9 | "parameters": [ 10 | { 11 | "name": "petId", 12 | "in": "path", 13 | "description": "ID of pet that needs to be fetched", 14 | "required": true, 15 | "type": "integer", 16 | "format": "int64" 17 | } 18 | ], 19 | "responses": { 20 | "200": { 21 | "description": "fun", 22 | "schema": {"$ref": "#/definitions/Pet"} 23 | }, 24 | "400": { 25 | "description": "Invalid ID supplied <= this is purely for documentation", 26 | "schema": {"$ref": "#/definitions/ErrorModel"} 27 | }, 28 | "default": { 29 | "description": "Unexpected error", 30 | "schema": {"$ref": "#/definitions/ErrorModel"} 31 | } 32 | } 33 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/operations/stringPathAndBoolQueryParamResource.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "Returns a pet based on ID", 3 | "summary": "Find pet by ID", 4 | "operationId": "getPetsById", 5 | "produces": [ 6 | "application/json", 7 | "text/html" 8 | ], 9 | "parameters": [ 10 | { 11 | "name": "petId", 12 | "in": "path", 13 | "description": "ID of pet that needs to be fetched", 14 | "required": true, 15 | "type": "integer", 16 | "format": "int64" 17 | }, 18 | { 19 | "name": "includeDetails", 20 | "in": "query", 21 | "description": "include details in response", 22 | "required": true, 23 | "type": "boolean" 24 | } 25 | ], 26 | "responses": { 27 | "200": { 28 | "description": "a pet to be returned", 29 | "schema": {"$ref": "#/definitions/Pet"} 30 | }, 31 | "default": { 32 | "description": "Unexpected error", 33 | "schema": {"$ref": "#/definitions/ErrorModel"} 34 | } 35 | } 36 | } -------------------------------------------------------------------------------- /schemas/v1.2/modelsObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/modelsObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "id", "properties" ], 6 | "properties": { 7 | "id": { "type": "string" }, 8 | "description": { "type": "string" }, 9 | "properties": { 10 | "type": "object", 11 | "additionalProperties": { "$ref": "#/definitions/propertyObject" } 12 | }, 13 | "subTypes": { 14 | "type": "array", 15 | "items": { "type": "string" }, 16 | "uniqueItems": true 17 | }, 18 | "discriminator": { "type": "string" } 19 | }, 20 | "dependencies": { 21 | "subTypes": [ "discriminator" ] 22 | }, 23 | "definitions": { 24 | "propertyObject": { 25 | "allOf": [ 26 | { 27 | "not": { "$ref": "#" } 28 | }, 29 | { 30 | "$ref": "dataTypeBase.json#" 31 | } 32 | ] 33 | } 34 | } 35 | } 36 | 37 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json: -------------------------------------------------------------------------------- 1 | { 2 | "get": { 3 | "description": "Returns a pet based on ID", 4 | "summary": "Find pet by ID", 5 | "operationId": "getPetsById", 6 | "produces": [ 7 | "application/json", 8 | "text/html" 9 | ], 10 | "parameters": [ 11 | { 12 | "name": "petId", 13 | "in": "path", 14 | "description": "ID of pet that needs to be fetched", 15 | "required": true, 16 | "type": "array", 17 | "items": { 18 | "type": "string" 19 | }, 20 | "collectionFormat": "csv" 21 | } 22 | ], 23 | "responses": { 24 | "200": { 25 | "description": "pet response", 26 | "schema": { 27 | "$ref": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#/definitions/Pet" 28 | } 29 | }, 30 | "default": { 31 | "description": "error payload", 32 | "schema": { 33 | "$ref": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#/definitions/ErrorModel" 34 | } 35 | } 36 | } 37 | } 38 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-minimal.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | swagger: "2.0" 3 | info: 4 | version: "1.0.0" 5 | title: "Swagger Petstore" 6 | description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" 7 | termsOfService: "http://swagger.io/terms/" 8 | contact: 9 | name: "Swagger API Team" 10 | license: 11 | name: "MIT" 12 | host: "petstore.swagger.io" 13 | basePath: "/api" 14 | schemes: 15 | - "http" 16 | consumes: 17 | - "application/json" 18 | produces: 19 | - "application/json" 20 | paths: 21 | /pets: 22 | get: 23 | description: "Returns all pets from the system that the user has access to" 24 | produces: 25 | - "application/json" 26 | responses: 27 | "200": 28 | description: "A list of pets." 29 | schema: 30 | type: "array" 31 | items: 32 | $ref: "#/definitions/Pet" 33 | definitions: 34 | Pet: 35 | type: "object" 36 | required: 37 | - "id" 38 | - "name" 39 | properties: 40 | id: 41 | type: "integer" 42 | format: "int64" 43 | name: 44 | type: "string" 45 | tag: 46 | type: "string" 47 | 48 | -------------------------------------------------------------------------------- /schemas/v1.2/parameterObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/parameterObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "allOf": [ 6 | { "$ref": "dataTypeBase.json#" }, 7 | { 8 | "required": [ "paramType", "name" ], 9 | "properties": { 10 | "paramType": { 11 | "enum": [ "path", "query", "body", "header", "form" ] 12 | }, 13 | "name": { "type": "string" }, 14 | "description": { "type": "string" }, 15 | "required": { "type": "boolean" }, 16 | "allowMultiple": { "type": "boolean" } 17 | } 18 | }, 19 | { 20 | "description": "type File requires special paramType and consumes", 21 | "oneOf": [ 22 | { 23 | "properties": { 24 | "type": { "not": { "enum": [ "File" ] } } 25 | } 26 | }, 27 | { 28 | "properties": { 29 | "type": { "enum": [ "File" ] }, 30 | "paramType": { "enum": [ "form" ] }, 31 | "consumes": { "enum": [ "multipart/form-data" ] } 32 | } 33 | } 34 | ] 35 | } 36 | ] 37 | } 38 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithMultipleProperties.json: -------------------------------------------------------------------------------- 1 | { 2 | "description": "true", 3 | "properties": { 4 | "booleanValue": { 5 | "type": "boolean" 6 | }, 7 | "byteValue": { 8 | "type": "string", 9 | "format": "byte" 10 | }, 11 | "dateTimeValue": { 12 | "type": "string", 13 | "format": "date-time" 14 | }, 15 | "int32Value": { 16 | "type": "integer", 17 | "format": "int32" 18 | }, 19 | "int64Value": { 20 | "type": "integer", 21 | "format": "int64" 22 | }, 23 | "stringValue": { 24 | "type": "string" 25 | }, 26 | "booleanArrayValue": { 27 | "type": "array", 28 | "items": { 29 | "type": "boolean" 30 | } 31 | }, 32 | "byteArrayValue": { 33 | "type": "array", 34 | "items": { 35 | "type": "string", 36 | "format": "byte" 37 | } 38 | }, 39 | "dateTimeArrayValue": { 40 | "type": "array", 41 | "items": { 42 | "type": "string", 43 | "format": "date-time" 44 | } 45 | }, 46 | "int32ArrayValue": { 47 | "type": "array", 48 | "items": { 49 | "type": "integer", 50 | "format": "int32" 51 | } 52 | }, 53 | "int64ArrayValue": { 54 | "type": "array", 55 | "items": { 56 | "type": "integer", 57 | "format": "int64" 58 | } 59 | }, 60 | "stringArrayValue": { 61 | "type": "array", 62 | "items": { 63 | "type": "string" 64 | } 65 | } 66 | } 67 | } -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-minimal.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team" 10 | }, 11 | "license": { 12 | "name": "MIT" 13 | } 14 | }, 15 | "host": "petstore.swagger.io", 16 | "basePath": "/api", 17 | "schemes": [ 18 | "http" 19 | ], 20 | "consumes": [ 21 | "application/json" 22 | ], 23 | "produces": [ 24 | "application/json" 25 | ], 26 | "paths": { 27 | "/pets": { 28 | "get": { 29 | "description": "Returns all pets from the system that the user has access to", 30 | "produces": [ 31 | "application/json" 32 | ], 33 | "responses": { 34 | "200": { 35 | "description": "A list of pets.", 36 | "schema": { 37 | "type": "array", 38 | "items": { 39 | "$ref": "#/definitions/Pet" 40 | } 41 | } 42 | } 43 | } 44 | } 45 | } 46 | }, 47 | "definitions": { 48 | "Pet": { 49 | "type": "object", 50 | "required": [ 51 | "id", 52 | "name" 53 | ], 54 | "properties": { 55 | "id": { 56 | "type": "integer", 57 | "format": "int64" 58 | }, 59 | "name": { 60 | "type": "string" 61 | }, 62 | "tag": { 63 | "type": "string" 64 | } 65 | } 66 | } 67 | } 68 | } -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{petId}": { 32 | "$ref": "https://raw.githubusercontent.com/swagger-api/swagger-spec/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json" 33 | } 34 | }, 35 | "definitions": { 36 | "Pet": { 37 | "required": [ 38 | "name" 39 | ], 40 | "properties": { 41 | "name": { 42 | "type": "string" 43 | }, 44 | "tag": { 45 | "type": "string" 46 | } 47 | } 48 | }, 49 | "ErrorModel": { 50 | "required": [ "code", "message" ], 51 | "properties": { 52 | "code": { 53 | "type": "integer", 54 | "format": "int32" 55 | }, 56 | "message": { 57 | "type": "string" 58 | } 59 | } 60 | } 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/models/modelWithComposition.json: -------------------------------------------------------------------------------- 1 | { 2 | "Pet": { 3 | "discriminator": "petType", 4 | "properties": { 5 | "name": { 6 | "type": "string" 7 | }, 8 | "petType": { 9 | "type": "string" 10 | } 11 | }, 12 | "required": [ 13 | "name", 14 | "petType" 15 | ] 16 | }, 17 | "Cat": { 18 | "description": "A representation of a cat", 19 | "allOf": [ 20 | { 21 | "$ref": "#/definitions/Pet" 22 | }, 23 | { 24 | "properties": { 25 | "huntingSkill": { 26 | "type": "string", 27 | "description": "The measured skill for hunting", 28 | "default": "lazy", 29 | "enum": [ 30 | "clueless", 31 | "lazy", 32 | "adventurous", 33 | "aggressive" 34 | ] 35 | } 36 | }, 37 | "required": [ 38 | "huntingSkill" 39 | ] 40 | } 41 | ] 42 | }, 43 | "Dog": { 44 | "description": "A representation of a dog", 45 | "allOf": [ 46 | { 47 | "$ref": "#/definitions/Pet" 48 | }, 49 | { 50 | "properties": { 51 | "packSize": { 52 | "type": "integer", 53 | "format": "int32", 54 | "description": "the size of the pack the dog is from", 55 | "default": 0, 56 | "minimum": 0 57 | } 58 | }, 59 | "required": [ 60 | "packSize" 61 | ] 62 | } 63 | ] 64 | }, 65 | "Fish": { 66 | "description": "A representation of a fish", 67 | "allOf": [ 68 | { 69 | "$ref": "#/definitions/Pet" 70 | }, 71 | { 72 | "properties": { 73 | "fins": { 74 | "type": "integer", 75 | "format": "int32", 76 | "description": "count of fins", 77 | "minimum": 0 78 | } 79 | }, 80 | "required": [ 81 | "fins" 82 | ] 83 | } 84 | ] 85 | } 86 | } -------------------------------------------------------------------------------- /schemas/v1.2/authorizationObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "additionalProperties": { 6 | "oneOf": [ 7 | { 8 | "$ref": "#/definitions/basicAuth" 9 | }, 10 | { 11 | "$ref": "#/definitions/apiKey" 12 | }, 13 | { 14 | "$ref": "#/definitions/oauth2" 15 | } 16 | ] 17 | }, 18 | "definitions": { 19 | "basicAuth": { 20 | "required": [ "type" ], 21 | "properties": { 22 | "type": { "enum": [ "basicAuth" ] } 23 | }, 24 | "additionalProperties": false 25 | }, 26 | "apiKey": { 27 | "required": [ "type", "passAs", "keyname" ], 28 | "properties": { 29 | "type": { "enum": [ "apiKey" ] }, 30 | "passAs": { "enum": [ "header", "query" ] }, 31 | "keyname": { "type": "string" } 32 | }, 33 | "additionalProperties": false 34 | }, 35 | "oauth2": { 36 | "type": "object", 37 | "required": [ "type", "grantTypes" ], 38 | "properties": { 39 | "type": { "enum": [ "oauth2" ] }, 40 | "scopes": { 41 | "type": "array", 42 | "items": { "$ref": "#/definitions/oauth2Scope" } 43 | }, 44 | "grantTypes": { "$ref": "oauth2GrantType.json#" } 45 | }, 46 | "additionalProperties": false 47 | }, 48 | "oauth2Scope": { 49 | "type": "object", 50 | "required": [ "scope" ], 51 | "properties": { 52 | "scope": { "type": "string" }, 53 | "description": { "type": "string" } 54 | }, 55 | "additionalProperties": false 56 | } 57 | } 58 | } 59 | 60 | -------------------------------------------------------------------------------- /schemas/v1.2/apiDeclaration.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "required": [ "swaggerVersion", "basePath", "apis" ], 6 | "properties": { 7 | "swaggerVersion": { "enum": [ "1.2" ] }, 8 | "apiVersion": { "type": "string" }, 9 | "basePath": { 10 | "type": "string", 11 | "format": "uri", 12 | "pattern": "^https?://" 13 | }, 14 | "resourcePath": { 15 | "type": "string", 16 | "format": "uri", 17 | "pattern": "^/" 18 | }, 19 | "apis": { 20 | "type": "array", 21 | "items": { "$ref": "#/definitions/apiObject" } 22 | }, 23 | "models": { 24 | "type": "object", 25 | "additionalProperties": { 26 | "$ref": "modelsObject.json#" 27 | } 28 | }, 29 | "produces": { "$ref": "#/definitions/mimeTypeArray" }, 30 | "consumes": { "$ref": "#/definitions/mimeTypeArray" }, 31 | "authorizations": { "$ref": "authorizationObject.json#" } 32 | }, 33 | "additionalProperties": false, 34 | "definitions": { 35 | "apiObject": { 36 | "type": "object", 37 | "required": [ "path", "operations" ], 38 | "properties": { 39 | "path": { 40 | "type": "string", 41 | "format": "uri-template", 42 | "pattern": "^/" 43 | }, 44 | "description": { "type": "string" }, 45 | "operations": { 46 | "type": "array", 47 | "items": { "$ref": "operationObject.json#" } 48 | } 49 | }, 50 | "additionalProperties": false 51 | }, 52 | "mimeTypeArray": { 53 | "type": "array", 54 | "items": { 55 | "type": "string", 56 | "format": "mime-type" 57 | }, 58 | "uniqueItems": true 59 | } 60 | } 61 | } 62 | -------------------------------------------------------------------------------- /schemas/v1.2/oauth2GrantType.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/oauth2GrantType.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "minProperties": 1, 6 | "properties": { 7 | "implicit": { "$ref": "#/definitions/implicit" }, 8 | "authorization_code": { "$ref": "#/definitions/authorizationCode" } 9 | }, 10 | "definitions": { 11 | "implicit": { 12 | "type": "object", 13 | "required": [ "loginEndpoint" ], 14 | "properties": { 15 | "loginEndpoint": { "$ref": "#/definitions/loginEndpoint" }, 16 | "tokenName": { "type": "string" } 17 | }, 18 | "additionalProperties": false 19 | }, 20 | "authorizationCode": { 21 | "type": "object", 22 | "required": [ "tokenEndpoint", "tokenRequestEndpoint" ], 23 | "properties": { 24 | "tokenEndpoint": { "$ref": "#/definitions/tokenEndpoint" }, 25 | "tokenRequestEndpoint": { "$ref": "#/definitions/tokenRequestEndpoint" } 26 | }, 27 | "additionalProperties": false 28 | }, 29 | "loginEndpoint": { 30 | "type": "object", 31 | "required": [ "url" ], 32 | "properties": { 33 | "url": { "type": "string", "format": "uri" } 34 | }, 35 | "additionalProperties": false 36 | }, 37 | "tokenEndpoint": { 38 | "type": "object", 39 | "required": [ "url" ], 40 | "properties": { 41 | "url": { "type": "string", "format": "uri" }, 42 | "tokenName": { "type": "string" } 43 | }, 44 | "additionalProperties": false 45 | }, 46 | "tokenRequestEndpoint": { 47 | "type": "object", 48 | "required": [ "url" ], 49 | "properties": { 50 | "url": { "type": "string", "format": "uri" }, 51 | "clientIdName": { "type": "string" }, 52 | "clientSecretName": { "type": "string" } 53 | }, 54 | "additionalProperties": false 55 | } 56 | } 57 | } -------------------------------------------------------------------------------- /examples/v3.0/callback-example.yaml: -------------------------------------------------------------------------------- 1 | paths: 2 | /streams: 3 | post: 4 | description: subscribes a client to receive out-of-band data 5 | parameters: 6 | - name: callbackUrl 7 | in: query 8 | required: true 9 | description: | 10 | the location where data will be sent. Must be network accessible 11 | by the source server 12 | schema: 13 | type: string 14 | format: uri 15 | example: https://tonys-server.com 16 | responses: 17 | '201': 18 | description: subscription successfully created 19 | content: 20 | application/json: 21 | schema: 22 | description: subscription information 23 | required: 24 | - subscriptionId 25 | properties: 26 | subscriptionId: 27 | description: this unique identifier allows management of the subscription 28 | type: string 29 | example: 2531329f-fb09-4ef7-887e-84e648214436 30 | callbacks: 31 | # the name `onData` is a convenience locator 32 | onData: 33 | # when data is sent, it will be sent to the `callbackUrl` provided 34 | # when making the subscription PLUS the suffix `/data` 35 | {$request.query.callbackUrl}/data: 36 | post: 37 | requestBody: 38 | description: subscription payload 39 | content: 40 | application/json: 41 | schema: 42 | properties: 43 | timestamp: 44 | type: string 45 | format: date-time 46 | userData: 47 | $ref: '#/components/schemas/UserLogData' 48 | responses: 49 | '202': 50 | description: | 51 | Your server implementation should return this HTTP status code 52 | if the data was received successfully 53 | '204': 54 | description: | 55 | Your server should return this HTTP status code if no longer interested 56 | in further updates 57 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/stringPathParamResource.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{petId}": { 32 | "get": { 33 | "description": "Returns a pet based on ID", 34 | "summary": "Find pet by ID", 35 | "operationId": "getPetsById", 36 | "produces": [ 37 | "application/json", 38 | "text/html" 39 | ], 40 | "parameters": [ 41 | { 42 | "name": "petId", 43 | "in": "path", 44 | "description": "ID of pet that needs to be fetched", 45 | "required": true, 46 | "type": "array", 47 | "items": { 48 | "type": "string" 49 | }, 50 | "collectionFormat": "csv" 51 | } 52 | ], 53 | "responses": { 54 | "200": { 55 | "description": "pet response", 56 | "schema": { 57 | "$ref": "#/definitions/Pet" 58 | } 59 | }, 60 | "default": { 61 | "description": "error payload", 62 | "schema": { 63 | "$ref": "#/definitions/ErrorModel" 64 | } 65 | } 66 | } 67 | } 68 | } 69 | }, 70 | "definitions": { 71 | "Pet": { 72 | "required": [ 73 | "name" 74 | ], 75 | "properties": { 76 | "name": { 77 | "type": "string" 78 | }, 79 | "tag": { 80 | "type": "string" 81 | } 82 | } 83 | }, 84 | "ErrorModel": { 85 | "required": [ "code", "message" ], 86 | "properties": { 87 | "code": { 88 | "type": "integer", 89 | "format": "int32" 90 | }, 91 | "message": { 92 | "type": "string" 93 | } 94 | } 95 | } 96 | } 97 | } 98 | -------------------------------------------------------------------------------- /schemas/v1.2/operationObject.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/operationObject.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "type": "object", 5 | "allOf": [ 6 | { "$ref": "dataTypeBase.json#" }, 7 | { 8 | "required": [ "method", "nickname", "parameters" ], 9 | "properties": { 10 | "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] }, 11 | "summary": { "type": "string", "maxLength": 120 }, 12 | "notes": { "type": "string" }, 13 | "nickname": { 14 | "type": "string", 15 | "pattern": "^[a-zA-Z0-9_]+$" 16 | }, 17 | "authorizations": { 18 | "type": "object", 19 | "additionalProperties": { 20 | "type": "array", 21 | "items": { 22 | "$ref": "authorizationObject.json#/definitions/oauth2Scope" 23 | } 24 | } 25 | }, 26 | "parameters": { 27 | "type": "array", 28 | "items": { "$ref": "parameterObject.json#" } 29 | }, 30 | "responseMessages": { 31 | "type": "array", 32 | "items": { "$ref": "#/definitions/responseMessageObject"} 33 | }, 34 | "produces": { "$ref": "#/definitions/mimeTypeArray" }, 35 | "consumes": { "$ref": "#/definitions/mimeTypeArray" }, 36 | "deprecated": { "enum": [ "true", "false" ] } 37 | } 38 | } 39 | ], 40 | "definitions": { 41 | "responseMessageObject": { 42 | "type": "object", 43 | "required": [ "code", "message" ], 44 | "properties": { 45 | "code": { "$ref": "#/definitions/rfc2616section10" }, 46 | "message": { "type": "string" }, 47 | "responseModel": { "type": "string" } 48 | } 49 | }, 50 | "rfc2616section10": { 51 | "type": "integer", 52 | "minimum": 100, 53 | "maximum": 600, 54 | "exclusiveMaximum": true 55 | }, 56 | "mimeTypeArray": { 57 | "type": "array", 58 | "items": { 59 | "type": "string", 60 | "format": "mime-type" 61 | }, 62 | "uniqueItems": true 63 | } 64 | } 65 | } 66 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/cascadingSchemes.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{petId}": { 32 | "get": { 33 | "description": "Returns a pet based on ID", 34 | "summary": "Find pet by ID", 35 | "operationId": "getPetsById", 36 | "produces": [ 37 | "application/json", 38 | "text/html" 39 | ], 40 | "parameters": [ 41 | { 42 | "name": "petId", 43 | "in": "path", 44 | "description": "ID of pet that needs to be fetched", 45 | "required": true, 46 | "type": "array", 47 | "items": { 48 | "type": "string" 49 | }, 50 | "collectionFormat": "csv" 51 | } 52 | ], 53 | "responses": { 54 | "200": { 55 | "description": "pet response", 56 | "schema": { 57 | "$ref": "#/definitions/Pet" 58 | } 59 | }, 60 | "default": { 61 | "description": "error payload", 62 | "schema": { 63 | "$ref": "#/definitions/ErrorModel" 64 | } 65 | } 66 | }, 67 | "schemes": [ "https" ] 68 | } 69 | } 70 | }, 71 | "definitions": { 72 | "Pet": { 73 | "required": [ 74 | "name" 75 | ], 76 | "properties": { 77 | "name": { 78 | "type": "string" 79 | }, 80 | "tag": { 81 | "type": "string" 82 | } 83 | } 84 | }, 85 | "ErrorModel": { 86 | "required": [ "code", "message" ], 87 | "properties": { 88 | "code": { 89 | "type": "integer", 90 | "format": "int32" 91 | }, 92 | "message": { 93 | "type": "string" 94 | } 95 | } 96 | } 97 | } 98 | } 99 | -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore.yaml: -------------------------------------------------------------------------------- 1 | swagger: "2.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | license: 6 | name: MIT 7 | host: petstore.swagger.io 8 | basePath: /v1 9 | schemes: 10 | - http 11 | consumes: 12 | - application/json 13 | produces: 14 | - application/json 15 | paths: 16 | /pets: 17 | get: 18 | summary: List all pets 19 | operationId: listPets 20 | tags: 21 | - pets 22 | parameters: 23 | - name: limit 24 | in: query 25 | description: How many items to return at one time (max 100) 26 | required: false 27 | type: integer 28 | format: int32 29 | responses: 30 | "200": 31 | description: An paged array of pets 32 | headers: 33 | x-next: 34 | type: string 35 | description: A link to the next page of responses 36 | schema: 37 | $ref: '#/definitions/Pets' 38 | default: 39 | description: unexpected error 40 | schema: 41 | $ref: '#/definitions/Error' 42 | post: 43 | summary: Create a pet 44 | operationId: createPets 45 | tags: 46 | - pets 47 | responses: 48 | "201": 49 | description: Null response 50 | default: 51 | description: unexpected error 52 | schema: 53 | $ref: '#/definitions/Error' 54 | /pets/{petId}: 55 | get: 56 | summary: Info for a specific pet 57 | operationId: showPetById 58 | tags: 59 | - pets 60 | parameters: 61 | - name: petId 62 | in: path 63 | required: true 64 | description: The id of the pet to retrieve 65 | type: string 66 | responses: 67 | "200": 68 | description: Expected response to a valid request 69 | schema: 70 | $ref: '#/definitions/Pets' 71 | default: 72 | description: unexpected error 73 | schema: 74 | $ref: '#/definitions/Error' 75 | definitions: 76 | Pet: 77 | required: 78 | - id 79 | - name 80 | properties: 81 | id: 82 | type: integer 83 | format: int64 84 | name: 85 | type: string 86 | tag: 87 | type: string 88 | Pets: 89 | type: array 90 | items: 91 | $ref: '#/definitions/Pet' 92 | Error: 93 | required: 94 | - code 95 | - message 96 | properties: 97 | code: 98 | type: integer 99 | format: int32 100 | message: 101 | type: string 102 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/resourceWithRelativeHost.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "basePath": "/v1", 18 | "schemes": [ 19 | "http", 20 | "https" 21 | ], 22 | "consumes": [ 23 | "application/json" 24 | ], 25 | "produces": [ 26 | "application/json", 27 | "application/xml" 28 | ], 29 | "paths": { 30 | "/pets/{id}": { 31 | "parameters": [ 32 | { 33 | "name": "id", 34 | "in": "path", 35 | "description": "ID of pet to use", 36 | "required": true, 37 | "type": "array", 38 | "items": { 39 | "type": "string" 40 | }, 41 | "collectionFormat": "csv" 42 | } 43 | ], 44 | "get": { 45 | "description": "Returns pets based on ID", 46 | "summary": "Find pets by ID", 47 | "operationId": "getPetsById", 48 | "produces": [ 49 | "application/json", 50 | "text/html" 51 | ], 52 | "responses": { 53 | "200": { 54 | "description": "pet response", 55 | "schema": { 56 | "type": "array", 57 | "items": { 58 | "$ref": "#/definitions/Pet" 59 | } 60 | } 61 | }, 62 | "default": { 63 | "description": "error payload", 64 | "schema": { 65 | "$ref": "#/definitions/ErrorModel" 66 | } 67 | } 68 | } 69 | } 70 | } 71 | }, 72 | "definitions": { 73 | "Pet": { 74 | "required": [ 75 | "name" 76 | ], 77 | "properties": { 78 | "name": { 79 | "type": "string" 80 | }, 81 | "tag": { 82 | "type": "string" 83 | } 84 | } 85 | }, 86 | "ErrorModel": { 87 | "required": [ "code", "message" ], 88 | "properties": { 89 | "code": { 90 | "type": "integer", 91 | "format": "int32" 92 | }, 93 | "message": { 94 | "type": "string" 95 | } 96 | } 97 | } 98 | } 99 | } 100 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/commonParameters.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{id}": { 32 | "parameters": [ 33 | { 34 | "name": "id", 35 | "in": "path", 36 | "description": "ID of pet to use", 37 | "required": true, 38 | "type": "array", 39 | "items": { 40 | "type": "string" 41 | }, 42 | "collectionFormat": "csv" 43 | } 44 | ], 45 | "get": { 46 | "description": "Returns pets based on ID", 47 | "summary": "Find pets by ID", 48 | "operationId": "getPetsById", 49 | "produces": [ 50 | "application/json", 51 | "text/html" 52 | ], 53 | "responses": { 54 | "200": { 55 | "description": "pet response", 56 | "schema": { 57 | "type": "array", 58 | "items": { 59 | "$ref": "#/definitions/Pet" 60 | } 61 | } 62 | }, 63 | "default": { 64 | "description": "error payload", 65 | "schema": { 66 | "$ref": "#/definitions/ErrorModel" 67 | } 68 | } 69 | } 70 | } 71 | } 72 | }, 73 | "definitions": { 74 | "Pet": { 75 | "required": [ 76 | "name" 77 | ], 78 | "properties": { 79 | "name": { 80 | "type": "string" 81 | }, 82 | "tag": { 83 | "type": "string" 84 | } 85 | } 86 | }, 87 | "ErrorModel": { 88 | "required": [ "code", "message" ], 89 | "properties": { 90 | "code": { 91 | "type": "integer", 92 | "format": "int32" 93 | }, 94 | "message": { 95 | "type": "string" 96 | } 97 | } 98 | } 99 | } 100 | } 101 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/reusableParameters.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{id}": { 32 | "get": { 33 | "description": "Returns pets based on ID", 34 | "summary": "Find pets by ID", 35 | "operationId": "getPetsById", 36 | "parameters": [ 37 | { "$ref": "#/parameters/skipParam" }, 38 | { "$ref": "#/parameters/limitParam" } 39 | ], 40 | "responses": { 41 | "200": { 42 | "description": "pet response", 43 | "schema": { 44 | "type": "array", 45 | "items": { 46 | "$ref": "#/definitions/Pet" 47 | } 48 | } 49 | }, 50 | "default": { 51 | "description": "error payload", 52 | "schema": { 53 | "$ref": "#/definitions/ErrorModel" 54 | } 55 | } 56 | } 57 | } 58 | } 59 | }, 60 | "parameters": { 61 | "skipParam": { 62 | "name": "skip", 63 | "in": "query", 64 | "description": "number of items to skip", 65 | "required": true, 66 | "type": "integer", 67 | "format": "int32" 68 | }, 69 | "limitParam": { 70 | "name": "limit", 71 | "in": "query", 72 | "description": "max records to return", 73 | "required": true, 74 | "type": "integer", 75 | "format": "int32" 76 | } 77 | }, 78 | "definitions": { 79 | "Pet": { 80 | "required": [ 81 | "name" 82 | ], 83 | "properties": { 84 | "name": { 85 | "type": "string" 86 | }, 87 | "tag": { 88 | "type": "string" 89 | } 90 | } 91 | }, 92 | "ErrorModel": { 93 | "required": [ "code", "message" ], 94 | "properties": { 95 | "code": { 96 | "type": "integer", 97 | "format": "int32" 98 | }, 99 | "message": { 100 | "type": "string" 101 | } 102 | } 103 | } 104 | } 105 | } 106 | -------------------------------------------------------------------------------- /schemas/v1.2/dataTypeBase.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataTypeBase.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "Data type fields (section 4.3.3)", 5 | "type": "object", 6 | "oneOf": [ 7 | { "required": [ "type" ] }, 8 | { "required": [ "$ref" ] } 9 | ], 10 | "properties": { 11 | "type": { "type": "string" }, 12 | "$ref": { "type": "string" }, 13 | "format": { "type": "string" }, 14 | "defaultValue": { 15 | "not": { "type": [ "array", "object", "null" ] } 16 | }, 17 | "enum": { 18 | "type": "array", 19 | "items": { "type": "string" }, 20 | "uniqueItems": true, 21 | "minItems": 1 22 | }, 23 | "minimum": { "type": "string" }, 24 | "maximum": { "type": "string" }, 25 | "items": { "$ref": "#/definitions/itemsObject" }, 26 | "uniqueItems": { "type": "boolean" } 27 | }, 28 | "dependencies": { 29 | "format": { 30 | "oneOf": [ 31 | { 32 | "properties": { 33 | "type": { "enum": [ "integer" ] }, 34 | "format": { "enum": [ "int32", "int64" ] } 35 | } 36 | }, 37 | { 38 | "properties": { 39 | "type": { "enum": [ "number" ] }, 40 | "format": { "enum": [ "float", "double" ] } 41 | } 42 | }, 43 | { 44 | "properties": { 45 | "type": { "enum": [ "string" ] }, 46 | "format": { 47 | "enum": [ "byte", "date", "date-time" ] 48 | } 49 | } 50 | } 51 | ] 52 | } 53 | }, 54 | "definitions": { 55 | "itemsObject": { 56 | "oneOf": [ 57 | { 58 | "type": "object", 59 | "required": [ "$ref" ], 60 | "properties": { 61 | "$ref": { "type": "string" } 62 | }, 63 | "additionalProperties": false 64 | }, 65 | { 66 | "allOf": [ 67 | { "$ref": "#" }, 68 | { 69 | "required": [ "type" ], 70 | "properties": { 71 | "type": {}, 72 | "format": {} 73 | }, 74 | "additionalProperties": false 75 | } 76 | ] 77 | } 78 | ] 79 | } 80 | } 81 | } 82 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/css/highlight.default.css: -------------------------------------------------------------------------------- 1 | /* 2 | 3 | Original style from softwaremaniacs.org (c) Ivan Sagalaev 4 | 5 | */ 6 | 7 | pre code { 8 | display: block; padding: 0.5em; 9 | background: #F0F0F0; 10 | } 11 | 12 | pre code, 13 | pre .subst, 14 | pre .tag .title, 15 | pre .lisp .title, 16 | pre .clojure .built_in, 17 | pre .nginx .title { 18 | color: black; 19 | } 20 | 21 | pre .string, 22 | pre .title, 23 | pre .constant, 24 | pre .parent, 25 | pre .tag .value, 26 | pre .rules .value, 27 | pre .rules .value .number, 28 | pre .preprocessor, 29 | pre .ruby .symbol, 30 | pre .ruby .symbol .string, 31 | pre .aggregate, 32 | pre .template_tag, 33 | pre .django .variable, 34 | pre .smalltalk .class, 35 | pre .addition, 36 | pre .flow, 37 | pre .stream, 38 | pre .bash .variable, 39 | pre .apache .tag, 40 | pre .apache .cbracket, 41 | pre .tex .command, 42 | pre .tex .special, 43 | pre .erlang_repl .function_or_atom, 44 | pre .markdown .header { 45 | color: #800; 46 | } 47 | 48 | pre .comment, 49 | pre .annotation, 50 | pre .template_comment, 51 | pre .diff .header, 52 | pre .chunk, 53 | pre .markdown .blockquote { 54 | color: #888; 55 | } 56 | 57 | pre .number, 58 | pre .date, 59 | pre .regexp, 60 | pre .literal, 61 | pre .smalltalk .symbol, 62 | pre .smalltalk .char, 63 | pre .go .constant, 64 | pre .change, 65 | pre .markdown .bullet, 66 | pre .markdown .link_url { 67 | color: #080; 68 | } 69 | 70 | pre .label, 71 | pre .javadoc, 72 | pre .ruby .string, 73 | pre .decorator, 74 | pre .filter .argument, 75 | pre .localvars, 76 | pre .array, 77 | pre .attr_selector, 78 | pre .important, 79 | pre .pseudo, 80 | pre .pi, 81 | pre .doctype, 82 | pre .deletion, 83 | pre .envvar, 84 | pre .shebang, 85 | pre .apache .sqbracket, 86 | pre .nginx .built_in, 87 | pre .tex .formula, 88 | pre .erlang_repl .reserved, 89 | pre .prompt, 90 | pre .markdown .link_label, 91 | pre .vhdl .attribute, 92 | pre .clojure .attribute, 93 | pre .coffeescript .property { 94 | color: #88F 95 | } 96 | 97 | pre .keyword, 98 | pre .id, 99 | pre .phpdoc, 100 | pre .title, 101 | pre .built_in, 102 | pre .aggregate, 103 | pre .css .tag, 104 | pre .javadoctag, 105 | pre .phpdoc, 106 | pre .yardoctag, 107 | pre .smalltalk .class, 108 | pre .winutils, 109 | pre .bash .variable, 110 | pre .apache .tag, 111 | pre .go .typename, 112 | pre .tex .command, 113 | pre .markdown .strong, 114 | pre .request, 115 | pre .status { 116 | font-weight: bold; 117 | } 118 | 119 | pre .markdown .emphasis { 120 | font-style: italic; 121 | } 122 | 123 | pre .nginx .built_in { 124 | font-weight: normal; 125 | } 126 | 127 | pre .coffeescript .javascript, 128 | pre .javascript .xml, 129 | pre .tex .formula, 130 | pre .xml .javascript, 131 | pre .xml .vbscript, 132 | pre .xml .css, 133 | pre .xml .cdata { 134 | opacity: 0.5; 135 | } 136 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/vendorExtensionExamples.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "x-swagger": { 4 | "addAnythingYouWant": true 5 | }, 6 | "info": { 7 | "x-swagger-info": "this is an example", 8 | "version": "1.0.9-abcd", 9 | "title": "Swagger Sample API", 10 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 11 | "termsOfService": "http://swagger.io/terms/", 12 | "contact": { 13 | "name": "Swagger API Team", 14 | "url": "http://swagger.io" 15 | }, 16 | "license": { 17 | "name": "Creative Commons 4.0 International", 18 | "url": "http://creativecommons.org/licenses/by/4.0/" 19 | } 20 | }, 21 | "host": "my.api.com", 22 | "basePath": "/v1", 23 | "schemes": [ 24 | "http", 25 | "https" 26 | ], 27 | "consumes": [ 28 | "application/json" 29 | ], 30 | "produces": [ 31 | "application/json", 32 | "application/xml" 33 | ], 34 | "paths": { 35 | "x-swagger-path-info": "vendor info", 36 | "/pets": { 37 | "x-vendor-method": {}, 38 | "get": { 39 | "x-vendor-operation-property": {}, 40 | "description": "Returns a pet based on ID", 41 | "summary": "Find pet by ID", 42 | "operationId": "getPetsById", 43 | "produces": [ 44 | "application/json", 45 | "text/html" 46 | ], 47 | "parameters": [ 48 | { 49 | "x-vendor-parameter-property": {}, 50 | "name": "petId", 51 | "in": "path", 52 | "description": "ID of pet that needs to be fetched", 53 | "required": true, 54 | "type": "array", 55 | "items": { 56 | "type": "string" 57 | }, 58 | "collectionFormat": "csv" 59 | } 60 | ], 61 | "responses": { 62 | "x-vendor-operation-response-property": {}, 63 | "200": { 64 | "description": "pet response", 65 | "schema": { 66 | "$ref": "#/definitions/Pet" 67 | } 68 | }, 69 | "default": { 70 | "description": "error payload", 71 | "schema": { 72 | "$ref": "#/definitions/ErrorModel" 73 | } 74 | } 75 | } 76 | } 77 | } 78 | }, 79 | "definitions": { 80 | "Pet": { 81 | "x-vendor-model-property": {}, 82 | "required": [ 83 | "name" 84 | ], 85 | "properties": { 86 | "name": { 87 | "type": "string" 88 | }, 89 | "tag": { 90 | "type": "string" 91 | } 92 | } 93 | }, 94 | "ErrorModel": { 95 | "required": [ "code", "message" ], 96 | "properties": { 97 | "code": { 98 | "type": "integer", 99 | "format": "int32" 100 | }, 101 | "message": { 102 | "type": "string" 103 | } 104 | } 105 | } 106 | } 107 | } 108 | -------------------------------------------------------------------------------- /examples/v3.0/petstore.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | license: 6 | name: MIT 7 | servers: 8 | - url: http://petstore.swagger.io/v1 9 | paths: 10 | /pets: 11 | get: 12 | summary: List all pets 13 | operationId: listPets 14 | tags: 15 | - pets 16 | parameters: 17 | - name: limit 18 | in: query 19 | description: How many items to return at one time (max 100) 20 | required: false 21 | schema: 22 | type: integer 23 | format: int32 24 | responses: 25 | 200: 26 | description: An paged array of pets 27 | headers: 28 | x-next: 29 | description: A link to the next page of responses 30 | schema: 31 | type: string 32 | content: 33 | application/json: 34 | schema: 35 | $ref: "#/components/schemas/Pets" 36 | default: 37 | description: unexpected error 38 | content: 39 | application/json: 40 | schema: 41 | $ref: "#/components/schemas/Error" 42 | post: 43 | summary: Create a pet 44 | operationId: createPets 45 | tags: 46 | - pets 47 | responses: 48 | 201: 49 | description: Null response 50 | default: 51 | description: unexpected error 52 | content: 53 | application/json: 54 | schema: 55 | $ref: "#/components/schemas/Error" 56 | /pets/{petId}: 57 | get: 58 | summary: Info for a specific pet 59 | operationId: showPetById 60 | tags: 61 | - pets 62 | parameters: 63 | - name: petId 64 | in: path 65 | required: true 66 | description: The id of the pet to retrieve 67 | schema: 68 | type: string 69 | responses: 70 | 200: 71 | description: Expected response to a valid request 72 | content: 73 | application/json: 74 | schema: 75 | $ref: "#/components/schemas/Pets" 76 | default: 77 | description: unexpected error 78 | content: 79 | application/json: 80 | schema: 81 | $ref: "#/components/schemas/Error" 82 | components: 83 | schemas: 84 | Pet: 85 | required: 86 | - id 87 | - name 88 | properties: 89 | id: 90 | type: integer 91 | format: int64 92 | name: 93 | type: string 94 | tag: 95 | type: string 96 | Pets: 97 | type: array 98 | items: 99 | $ref: "#/components/schemas/Pet" 100 | Error: 101 | required: 102 | - code 103 | - message 104 | properties: 105 | code: 106 | type: integer 107 | format: int32 108 | message: 109 | type: string 110 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/multipleMimeTypes.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "text/plain; charset=utf-8", 25 | "application/json", 26 | "application/vnd.github+json", 27 | "application/vnd.github.v3+json", 28 | "application/vnd.github.v3.raw+json", 29 | "application/vnd.github.v3.text+json", 30 | "application/vnd.github.v3.html+json", 31 | "application/vnd.github.v3.full+json", 32 | "application/vnd.github.v3.diff", 33 | "application/vnd.github.v3.patch" 34 | ], 35 | "produces": [ 36 | "application/json", 37 | "application/xml" 38 | ], 39 | "paths": { 40 | "/pets/{id}": { 41 | "parameters": [ 42 | { 43 | "name": "id", 44 | "in": "path", 45 | "description": "ID of pet to use", 46 | "required": true, 47 | "type": "array", 48 | "items": { 49 | "type": "string" 50 | }, 51 | "collectionFormat": "csv" 52 | } 53 | ], 54 | "get": { 55 | "description": "Returns pets based on ID", 56 | "summary": "Find pets by ID", 57 | "operationId": "getPetsById", 58 | "produces": [ 59 | "application/json", 60 | "text/html" 61 | ], 62 | "responses": { 63 | "200": { 64 | "description": "pet response", 65 | "schema": { 66 | "type": "array", 67 | "items": { 68 | "$ref": "#/definitions/Pet" 69 | } 70 | } 71 | }, 72 | "default": { 73 | "description": "error payload", 74 | "schema": { 75 | "$ref": "#/definitions/ErrorModel" 76 | } 77 | } 78 | } 79 | } 80 | } 81 | }, 82 | "definitions": { 83 | "Pet": { 84 | "required": [ 85 | "name" 86 | ], 87 | "properties": { 88 | "name": { 89 | "type": "string" 90 | }, 91 | "tag": { 92 | "type": "string" 93 | } 94 | } 95 | }, 96 | "ErrorModel": { 97 | "required": [ "code", "message" ], 98 | "properties": { 99 | "code": { 100 | "type": "integer", 101 | "format": "int32" 102 | }, 103 | "message": { 104 | "type": "string" 105 | } 106 | } 107 | } 108 | } 109 | } 110 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/taggedResource.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "x-swagger": { 4 | "addAnythingYouWant": true 5 | }, 6 | "info": { 7 | "x-swagger-info": "this is an example", 8 | "version": "1.0.9-abcd", 9 | "title": "Swagger Sample API", 10 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 11 | "termsOfService": "http://swagger.io/terms/", 12 | "contact": { 13 | "name": "Swagger API Team", 14 | "url": "http://swagger.io" 15 | }, 16 | "license": { 17 | "name": "Creative Commons 4.0 International", 18 | "url": "http://creativecommons.org/licenses/by/4.0/" 19 | } 20 | }, 21 | "host": "my.api.com", 22 | "basePath": "/v1", 23 | "schemes": [ 24 | "http", 25 | "https" 26 | ], 27 | "consumes": [ 28 | "application/json" 29 | ], 30 | "produces": [ 31 | "application/json", 32 | "application/xml" 33 | ], 34 | "tags": [ 35 | { 36 | "name": "pets" 37 | } 38 | ], 39 | "paths": { 40 | "x-swagger-path-info": "vendor info", 41 | "/pets": { 42 | "x-vendor-method": {}, 43 | "get": { 44 | "x-vendor-operation-property": {}, 45 | "description": "Returns a pet based on ID", 46 | "summary": "Find pet by ID", 47 | "operationId": "getPetsById", 48 | "produces": [ 49 | "application/json", 50 | "text/html" 51 | ], 52 | "parameters": [ 53 | { 54 | "x-vendor-parameter-property": {}, 55 | "name": "petId", 56 | "in": "path", 57 | "description": "ID of pet that needs to be fetched", 58 | "required": true, 59 | "type": "array", 60 | "items": { 61 | "type": "string" 62 | }, 63 | "collectionFormat": "csv" 64 | } 65 | ], 66 | "responses": { 67 | "x-vendor-operation-response-property": {}, 68 | "200": { 69 | "description": "pet response", 70 | "schema": { 71 | "$ref": "#/definitions/Pet" 72 | } 73 | }, 74 | "default": { 75 | "description": "error payload", 76 | "schema": { 77 | "$ref": "#/definitions/ErrorModel" 78 | } 79 | } 80 | } 81 | } 82 | } 83 | }, 84 | "definitions": { 85 | "Pet": { 86 | "x-vendor-model-property": {}, 87 | "required": [ 88 | "name" 89 | ], 90 | "properties": { 91 | "name": { 92 | "type": "string" 93 | }, 94 | "tag": { 95 | "type": "string" 96 | } 97 | } 98 | }, 99 | "ErrorModel": { 100 | "required": [ "code", "message" ], 101 | "properties": { 102 | "code": { 103 | "type": "integer", 104 | "format": "int32" 105 | }, 106 | "message": { 107 | "type": "string" 108 | } 109 | } 110 | } 111 | } 112 | } 113 | -------------------------------------------------------------------------------- /fixtures/v2.0/json/resources/resourceWithExamplePayload.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.9-abcd", 5 | "title": "Swagger Sample API", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "url": "http://swagger.io" 11 | }, 12 | "license": { 13 | "name": "Creative Commons 4.0 International", 14 | "url": "http://creativecommons.org/licenses/by/4.0/" 15 | } 16 | }, 17 | "host": "my.api.com", 18 | "basePath": "/v1", 19 | "schemes": [ 20 | "http", 21 | "https" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json", 28 | "application/xml" 29 | ], 30 | "paths": { 31 | "/pets/{petId}": { 32 | "get": { 33 | "description": "Returns a pet based on ID", 34 | "summary": "Find pet by ID", 35 | "operationId": "getPetsById", 36 | "produces": [ 37 | "application/json", 38 | "text/html" 39 | ], 40 | "parameters": [ 41 | { 42 | "name": "petId", 43 | "in": "path", 44 | "description": "ID of pet that needs to be fetched", 45 | "required": true, 46 | "type": "array", 47 | "items": { 48 | "type": "string" 49 | }, 50 | "collectionFormat": "csv" 51 | } 52 | ], 53 | "responses": { 54 | "200": { 55 | "description": "pet response", 56 | "schema": { 57 | "$ref": "#/definitions/Pet" 58 | }, 59 | "examples": { 60 | "application/json": { 61 | "id": 9, 62 | "category": { 63 | "name": "domestic" 64 | }, 65 | "name": "monster", 66 | "tags": [ 67 | { 68 | "name": "for sale" 69 | } 70 | ], 71 | "status": "alive" 72 | } 73 | } 74 | }, 75 | "default": { 76 | "description": "error payload", 77 | "schema": { 78 | "$ref": "#/definitions/ErrorModel" 79 | } 80 | } 81 | } 82 | } 83 | } 84 | }, 85 | "definitions": { 86 | "Pet": { 87 | "required": [ 88 | "name" 89 | ], 90 | "properties": { 91 | "name": { 92 | "type": "string", 93 | "example": "cat" 94 | }, 95 | "tag": { 96 | "type": "string", 97 | "example": "for sale" 98 | } 99 | } 100 | }, 101 | "ErrorModel": { 102 | "required": [ "code", "message" ], 103 | "properties": { 104 | "code": { 105 | "type": "integer", 106 | "format": "int32" 107 | }, 108 | "message": { 109 | "type": "string" 110 | } 111 | } 112 | } 113 | } 114 | } 115 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Swagger UI 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 47 | 48 | 49 | 50 | 67 | 68 |
69 |   70 |
71 | 72 |
73 | 74 |
75 | 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /versions/smartapi-list.php: -------------------------------------------------------------------------------- 1 | <\/a>([^\n]+)/",$str, $header_labels); 10 | foreach($header_labels[2] AS $id => $label) {$header_labels[2][$id] = trim($label);} 11 | function getHeaderLink($label) 12 | { 13 | global $header_labels; 14 | $id = array_search($label, $header_labels[2]); 15 | return $header_labels[1][$id]; 16 | } 17 | $list = preg_split("/#### <\/a>/",$str, -1); 18 | 19 | array_shift($list); 20 | array_shift($list); 21 | array_shift($list); 22 | array_shift($list); 23 | array_shift($list); 24 | foreach($list as $i => $item) { 25 | $a = explode("\n",$item, 2); 26 | $object_label = trim($a[0]); 27 | 28 | // now find the smartapi section 29 | $record = false; 30 | $buf = ''; 31 | $a = explode("\n",$a[1]); 32 | foreach($a AS $b) { 33 | 34 | if($record === true) { 35 | //if(strlen(trim($b)) == 0) $record = false; 36 | if(strstr($b,"####")) $record = false; 37 | else { 38 | $buf .= $b.PHP_EOL; 39 | 40 | if(strstr($b,"<\/a>(.*)/",$cols[0],$m); 52 | $link = trim($m[1]); 53 | $field = trim($m[2]); 54 | 55 | // recommendation 56 | preg_match('/\*\*([^\*]+)/',$desc,$m); //([^*]+)**/',$desc,$m); 57 | $rec = ''; 58 | if(isset($m[1])) { 59 | $rec = $m[1]; 60 | $desc = substr($desc, strlen($rec)+5); 61 | } 62 | $desc = str_replace("https://github.com/WebsmartAPI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#","https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md", $desc); 63 | 64 | $mylist[$object_label][$field]['rec'] = $rec; 65 | $mylist[$object_label][$field]['desc'] = trim($desc); 66 | $mylist[$object_label][$field]['datatype'] = $datatype; 67 | $mylist[$object_label][$field]['link'] = $link; 68 | } 69 | } 70 | } 71 | if(strstr($b,"##### smartAPI") !== FALSE) { 72 | $record = true; 73 | } 74 | } 75 | 76 | } 77 | 78 | // markdown 79 | $file = "smartapi-list.md"; 80 | $fp = fopen($file,"w"); 81 | fwrite($fp,"smartAPI specific elements automatically generated from parent document".PHP_EOL.PHP_EOL); 82 | fwrite($fp,"Object | Field | Recommendation | Datatype | Description".PHP_EOL); 83 | fwrite($fp,"---|:---:|:---:|:---:|---".PHP_EOL); 84 | foreach($mylist AS $object => $o) { 85 | foreach($o as $field => $field_desc) { 86 | fwrite($fp, 87 | ''.$object.'' 88 | ."|".''.$field.'' 89 | ."|".$field_desc['rec'] 90 | ."|".$field_desc['datatype'] 91 | ."|".$field_desc['desc'] 92 | .PHP_EOL); 93 | } 94 | } 95 | fclose($fp); 96 | 97 | echo "$file generated".PHP_EOL; -------------------------------------------------------------------------------- /guidelines/v2.0/EXTENSIONS.md: -------------------------------------------------------------------------------- 1 | # OpenAPI Extensions 2 | 3 | The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI document., allowing 4 | API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always 5 | prefixed by "x-" and can have any valid JSON format value. 6 | 7 | Currently extension properties are supported in the following definition objects: 8 | 9 | * within the [info object](/versions/2.0.md#info-object) 10 | * within the [paths object](/versions/2.0.md#paths-object) 11 | * within the [path-item object](/versions/2.0.md#path-item-object) 12 | * within the [operation object](/versions/2.0.md#operationObject) 13 | * within the [parameter object](/versions/2.0.md#parameterObject) 14 | * within the [responses object](/versions/2.0.md#responses-object) 15 | * within the [tag object](/versions/2.0.md#tag-object) 16 | * within the [security-scheme object](/versions/2.0.md#security-scheme-object) 17 | 18 | For example, a vendor extension that adds apis.json specific metadata to an OpenAPI definition might look as follows: 19 | 20 | ```json 21 | { 22 | "swagger": "2.0", 23 | "info": { 24 | "version": "1.0", 25 | "title": "Analysis", 26 | "description" : "Provides access to blog posts and analysis across the API Evangelist network.", 27 | "x-apis-json" : { 28 | "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", 29 | "humanURL": "http://developer.apievangelist.com", 30 | "baseURL": "http://api.apievangelist.com/definitions/Analysis", 31 | "tags": [ 32 | "blog", 33 | "industry", 34 | "analysis", 35 | "new", 36 | "API", 37 | "Application Programming Interface" 38 | ], 39 | "properties": [ 40 | { 41 | "type": "X-signup", 42 | "url": "https://apievangelist.3scale.net/" 43 | }, 44 | { 45 | "type": "X-blog", 46 | "url": "http://developer.apievangelist.com/blog/" 47 | }, 48 | { 49 | "type": "X-apicommonsmanifest", 50 | "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json" 51 | } 52 | ], 53 | } 54 | }, 55 | "basePath": "/", 56 | "paths": { 57 | ... 58 | } 59 | } 60 | ``` 61 | 62 | This could be used by corresponding tooling that builds apis.json files for OpenAPI definitions, the advantage being that all metadata 63 | for the API is within one definition instead of spread out amongst multiple files. 64 | 65 | Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters, 66 | for example as follows: 67 | 68 | ```json 69 | { 70 | ... 71 | "socialSecurityNumber": { 72 | "name": "socialSecurityNumber", 73 | "in": "query", 74 | "description": "a social security number", 75 | "required": false, 76 | "type": "string", 77 | "x-jwe-encryption" : { 78 | "algorithm" : "RSA-OAEP", 79 | "encryption" : "A256GCM" 80 | } 81 | } 82 | } 83 | ... 84 | } 85 | 86 | ``` 87 | An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line 88 | with the JWE standard. 89 | 90 | ## Annotations 91 | 92 | The OpenAPI-specific annotations currently available for jax-rs APIs do not support the addition of extension data. 93 | -------------------------------------------------------------------------------- /IMPLEMENTATIONS.md: -------------------------------------------------------------------------------- 1 | ### Implementations 2 | 3 | Below is a list of known tooling that implements the 3.0.0 specification. Because 4 | the 3.0.0 specification has not yet been released, refer to the details of projects listed below for any notes about stability and roadmap. The process 5 | to create the best possible 3.0.0 specification includes feedback from end-users 6 | and tooling creators. We strongly encourage draft tooling be 7 | made available for early users of the OAS. 8 | 9 | These tools are not necessarily endorsed by the OAI. 10 | 11 | #### Low-Level tooling 12 | 13 | | Title | Project Link | Language |Description | 14 | |----------------|--------------|----------|---------------------| 15 | | swagger-parser | [GitHub/swagger-api](https://github.com/swagger-api/swagger-parser/tree/feature/3.0.0-rc0) | Java | Swagger 1.0, 1.1, 1.2, 2.0 to Open API Specification converter | 16 | | swagger-models | [GitHub/swagger-api](https://github.com/swagger-api/swagger-core/tree/feature/3.0.0-rc0/modules/swagger-models) | Java | Open API 3.0 Java Pojos | 17 | | KaiZen OpenAPI Parser | [GitHub/RepreZen/KaiZen-OpenAPI-Parser](https://github.com/RepreZen/KaiZen-OpenAPI-Parser) | Java | High-performance Parser, Validator, and Java Object Model for OpenAPI 3.x | 18 | | openapi3-ts | [GitHub/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts | 19 | | swagger2openapi | [GitHub/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator | 20 | | Tavis.OpenApi | [GitHub/tavis-sofware/Tavis.OpenApi](https://github.com/tavis-software/Tavis.OpenApi/) | dotnet | C# based parser with definition validation and migration support from V2 | 21 | 22 | 23 | #### Editors 24 | 25 | | Title | Project Link | Language |Description | 26 | |----------------|--------------|----------|---------------------| 27 | | KaiZen OpenAPI Editor | [GitHub/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 | 28 | | RepreZen API Studio | [RepreZen.com/OpenAPI](https://www.reprezen.com/OpenAPI) | Java | Commercial desktop IDE for API design, documentation & development | 29 | | OpenApi-gui | [GitHub/Mermade/openapi-gui](https://github.com/Mermade/openapi-gui) | Node.js | GUI / visual editor for creating and editing OpenApi / Swagger definitions | 30 | 31 | 32 | #### User Interfaces 33 | 34 | | Title | Project Link | Language |Description | 35 | |----------------|--------------|----------|---------------------| 36 | | openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. | 37 | | lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 | 38 | 39 | 40 | #### Server Implementations 41 | 42 | 43 | #### Code Generators 44 | 45 | | Title | Project Link | Language |Description | 46 | |----------------|--------------|----------|---------------------| 47 | | baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. | 48 | | Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. | 49 | | serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration | 50 | -------------------------------------------------------------------------------- /examples/v2.0/json/petstore.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "license": { 7 | "name": "MIT" 8 | } 9 | }, 10 | "host": "petstore.swagger.io", 11 | "basePath": "/v1", 12 | "schemes": [ 13 | "http" 14 | ], 15 | "consumes": [ 16 | "application/json" 17 | ], 18 | "produces": [ 19 | "application/json" 20 | ], 21 | "paths": { 22 | "/pets": { 23 | "get": { 24 | "summary": "List all pets", 25 | "operationId": "listPets", 26 | "tags": [ 27 | "pets" 28 | ], 29 | "parameters": [ 30 | { 31 | "name": "limit", 32 | "in": "query", 33 | "description": "How many items to return at one time (max 100)", 34 | "required": false, 35 | "type": "integer", 36 | "format": "int32" 37 | } 38 | ], 39 | "responses": { 40 | "200": { 41 | "description": "An paged array of pets", 42 | "headers": { 43 | "x-next": { 44 | "type": "string", 45 | "description": "A link to the next page of responses" 46 | } 47 | }, 48 | "schema": { 49 | "$ref": "#/definitions/Pets" 50 | } 51 | }, 52 | "default": { 53 | "description": "unexpected error", 54 | "schema": { 55 | "$ref": "#/definitions/Error" 56 | } 57 | } 58 | } 59 | }, 60 | "post": { 61 | "summary": "Create a pet", 62 | "operationId": "createPets", 63 | "tags": [ 64 | "pets" 65 | ], 66 | "responses": { 67 | "201": { 68 | "description": "Null response" 69 | }, 70 | "default": { 71 | "description": "unexpected error", 72 | "schema": { 73 | "$ref": "#/definitions/Error" 74 | } 75 | } 76 | } 77 | } 78 | }, 79 | "/pets/{petId}": { 80 | "get": { 81 | "summary": "Info for a specific pet", 82 | "operationId": "showPetById", 83 | "tags": [ 84 | "pets" 85 | ], 86 | "parameters": [ 87 | { 88 | "name": "petId", 89 | "in": "path", 90 | "required": true, 91 | "description": "The id of the pet to retrieve", 92 | "type": "string" 93 | } 94 | ], 95 | "responses": { 96 | "200": { 97 | "description": "Expected response to a valid request", 98 | "schema": { 99 | "$ref": "#/definitions/Pets" 100 | } 101 | }, 102 | "default": { 103 | "description": "unexpected error", 104 | "schema": { 105 | "$ref": "#/definitions/Error" 106 | } 107 | } 108 | } 109 | } 110 | } 111 | }, 112 | "definitions": { 113 | "Pet": { 114 | "required": [ 115 | "id", 116 | "name" 117 | ], 118 | "properties": { 119 | "id": { 120 | "type": "integer", 121 | "format": "int64" 122 | }, 123 | "name": { 124 | "type": "string" 125 | }, 126 | "tag": { 127 | "type": "string" 128 | } 129 | } 130 | }, 131 | "Pets": { 132 | "type": "array", 133 | "items": { 134 | "$ref": "#/definitions/Pet" 135 | } 136 | }, 137 | "Error": { 138 | "required": [ 139 | "code", 140 | "message" 141 | ], 142 | "properties": { 143 | "code": { 144 | "type": "integer", 145 | "format": "int32" 146 | }, 147 | "message": { 148 | "type": "string" 149 | } 150 | } 151 | } 152 | } 153 | } -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/pom.xml: -------------------------------------------------------------------------------- 1 | 3 | 4.0.0 4 | io.swagger 5 | swagger-demo 6 | jar 7 | swagger-demo 8 | 1.0.1-SNAPSHOT 9 | 10 | 2.2.0 11 | 12 | 13 | 14 | src/main/scala 15 | src/test/scala 16 | 17 | 18 | net.alchim31.maven 19 | scala-maven-plugin 20 | ${maven-plugin.version} 21 | 22 | 23 | 24 | compile 25 | testCompile 26 | 27 | 28 | 29 | 30 | 31 | -Xms64m 32 | -Xmx1024m 33 | 34 | 35 | 36 | 37 | maven-surefire-plugin 38 | 39 | once 40 | false 41 | 42 | 43 | 44 | maven-dependency-plugin 45 | 46 | 47 | package 48 | 49 | copy-dependencies 50 | 51 | 52 | ${project.build.directory}/lib 53 | 54 | 55 | 56 | 57 | 58 | org.mortbay.jetty 59 | jetty-maven-plugin 60 | ${jetty-version} 61 | 62 | 63 | / 64 | 65 | 66 | 67 | 8000 68 | 60000 69 | 8443 70 | 71 | 72 | 73 | 74 | 75 | start-jetty 76 | pre-integration-test 77 | 78 | run 79 | 80 | 81 | 0 82 | true 83 | 84 | 85 | 86 | stop-jetty 87 | post-integration-test 88 | 89 | stop 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | sonatype-snapshots 99 | https://oss.sonatype.org/content/repositories/snapshots 100 | 101 | 102 | sonatype-releases 103 | https://oss.sonatype.org/content/repositories/releases 104 | 105 | 106 | 107 | 3.1.0 108 | 7.6.0.v20120127 109 | 110 | 111 | 112 | -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-expanded.yaml: -------------------------------------------------------------------------------- 1 | swagger: "2.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification 6 | termsOfService: http://swagger.io/terms/ 7 | contact: 8 | name: Swagger API Team 9 | email: foo@example.com 10 | url: http://madskristensen.net 11 | license: 12 | name: MIT 13 | url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT 14 | host: petstore.swagger.io 15 | basePath: /api 16 | schemes: 17 | - http 18 | consumes: 19 | - application/json 20 | produces: 21 | - application/json 22 | paths: 23 | /pets: 24 | get: 25 | description: | 26 | Returns all pets from the system that the user has access to 27 | operationId: findPets 28 | parameters: 29 | - name: tags 30 | in: query 31 | description: tags to filter by 32 | required: false 33 | type: array 34 | collectionFormat: csv 35 | items: 36 | type: string 37 | - name: limit 38 | in: query 39 | description: maximum number of results to return 40 | required: false 41 | type: integer 42 | format: int32 43 | responses: 44 | "200": 45 | description: pet response 46 | schema: 47 | type: array 48 | items: 49 | $ref: '#/definitions/Pet' 50 | default: 51 | description: unexpected error 52 | schema: 53 | $ref: '#/definitions/Error' 54 | post: 55 | description: Creates a new pet in the store. Duplicates are allowed 56 | operationId: addPet 57 | parameters: 58 | - name: pet 59 | in: body 60 | description: Pet to add to the store 61 | required: true 62 | schema: 63 | $ref: '#/definitions/NewPet' 64 | responses: 65 | "200": 66 | description: pet response 67 | schema: 68 | $ref: '#/definitions/Pet' 69 | default: 70 | description: unexpected error 71 | schema: 72 | $ref: '#/definitions/Error' 73 | /pets/{id}: 74 | get: 75 | description: Returns a user based on a single ID, if the user does not have access to the pet 76 | operationId: find pet by id 77 | parameters: 78 | - name: id 79 | in: path 80 | description: ID of pet to fetch 81 | required: true 82 | type: integer 83 | format: int64 84 | responses: 85 | "200": 86 | description: pet response 87 | schema: 88 | $ref: '#/definitions/Pet' 89 | default: 90 | description: unexpected error 91 | schema: 92 | $ref: '#/definitions/Error' 93 | delete: 94 | description: deletes a single pet based on the ID supplied 95 | operationId: deletePet 96 | parameters: 97 | - name: id 98 | in: path 99 | description: ID of pet to delete 100 | required: true 101 | type: integer 102 | format: int64 103 | responses: 104 | "204": 105 | description: pet deleted 106 | default: 107 | description: unexpected error 108 | schema: 109 | $ref: '#/definitions/Error' 110 | definitions: 111 | Pet: 112 | allOf: 113 | - $ref: '#/definitions/NewPet' 114 | - required: 115 | - id 116 | properties: 117 | id: 118 | type: integer 119 | format: int64 120 | 121 | NewPet: 122 | required: 123 | - name 124 | properties: 125 | name: 126 | type: string 127 | tag: 128 | type: string 129 | 130 | Error: 131 | required: 132 | - code 133 | - message 134 | properties: 135 | code: 136 | type: integer 137 | format: int32 138 | message: 139 | type: string 140 | -------------------------------------------------------------------------------- /fixtures/v1.2/helloworld/server/src/main/webapp/lib/jquery.ba-bbq.min.js: -------------------------------------------------------------------------------- 1 | /* 2 | * jQuery BBQ: Back Button & Query Library - v1.2.1 - 2/17/2010 3 | * http://benalman.com/projects/jquery-bbq-plugin/ 4 | * 5 | * Copyright (c) 2010 "Cowboy" Ben Alman 6 | * Dual licensed under the MIT and GPL licenses. 7 | * http://benalman.com/about/license/ 8 | */ 9 | (function($,p){var i,m=Array.prototype.slice,r=decodeURIComponent,a=$.param,c,l,v,b=$.bbq=$.bbq||{},q,u,j,e=$.event.special,d="hashchange",A="querystring",D="fragment",y="elemUrlAttr",g="location",k="href",t="src",x=/^.*\?|#.*$/g,w=/^.*\#/,h,C={};function E(F){return typeof F==="string"}function B(G){var F=m.call(arguments,1);return function(){return G.apply(this,F.concat(m.call(arguments)))}}function n(F){return F.replace(/^[^#]*#?(.*)$/,"$1")}function o(F){return F.replace(/(?:^[^?#]*\?([^#]*).*$)?.*/,"$1")}function f(H,M,F,I,G){var O,L,K,N,J;if(I!==i){K=F.match(H?/^([^#]*)\#?(.*)$/:/^([^#?]*)\??([^#]*)(#?.*)/);J=K[3]||"";if(G===2&&E(I)){L=I.replace(H?w:x,"")}else{N=l(K[2]);I=E(I)?l[H?D:A](I):I;L=G===2?I:G===1?$.extend({},I,N):$.extend({},N,I);L=a(L);if(H){L=L.replace(h,r)}}O=K[1]+(H?"#":L||!K[1]?"?":"")+L+J}else{O=M(F!==i?F:p[g][k])}return O}a[A]=B(f,0,o);a[D]=c=B(f,1,n);c.noEscape=function(G){G=G||"";var F=$.map(G.split(""),encodeURIComponent);h=new RegExp(F.join("|"),"g")};c.noEscape(",/");$.deparam=l=function(I,F){var H={},G={"true":!0,"false":!1,"null":null};$.each(I.replace(/\+/g," ").split("&"),function(L,Q){var K=Q.split("="),P=r(K[0]),J,O=H,M=0,R=P.split("]["),N=R.length-1;if(/\[/.test(R[0])&&/\]$/.test(R[N])){R[N]=R[N].replace(/\]$/,"");R=R.shift().split("[").concat(R);N=R.length-1}else{N=0}if(K.length===2){J=r(K[1]);if(F){J=J&&!isNaN(J)?+J:J==="undefined"?i:G[J]!==i?G[J]:J}if(N){for(;M<=N;M++){P=R[M]===""?O.length:R[M];O=O[P]=M').hide().insertAfter("body")[0].contentWindow;q=function(){return a(n.document[c][l])};o=function(u,s){if(u!==s){var t=n.document;t.open().close();t[c].hash="#"+u}};o(a())}}m.start=function(){if(r){return}var t=a();o||p();(function s(){var v=a(),u=q(t);if(v!==t){o(t=v,u);$(i).trigger(d)}else{if(u!==t){i[c][l]=i[c][l].replace(/#.*/,"")+"#"+u}}r=setTimeout(s,$[d+"Delay"])})()};m.stop=function(){if(!n){r&&clearTimeout(r);r=0}};return m})()})(jQuery,this); -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-separate/spec/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: "2.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification 6 | termsOfService: http://helloreverb.com/terms/ 7 | contact: 8 | name: Wordnik API Team 9 | email: foo@example.com 10 | url: http://madskristensen.net 11 | license: 12 | name: MIT 13 | url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT 14 | host: petstore.swagger.wordnik.com 15 | basePath: /api 16 | schemes: 17 | - http 18 | consumes: 19 | - application/json 20 | produces: 21 | - application/json 22 | paths: 23 | /pets: 24 | get: 25 | description: | 26 | Returns all pets from the system that the user has access to 27 | Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. 28 | 29 | Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. 30 | operationId: findPets 31 | parameters: 32 | - $ref: 'parameters.yaml#/tagsParam' 33 | - $ref: 'parameters.yaml#/limitsParam' 34 | responses: 35 | "200": 36 | description: pet response 37 | schema: 38 | type: array 39 | items: 40 | $ref: 'Pet.yaml' 41 | default: 42 | description: unexpected error 43 | schema: 44 | $ref: '../common/Error.yaml' 45 | post: 46 | description: Creates a new pet in the store. Duplicates are allowed 47 | operationId: addPet 48 | parameters: 49 | - name: pet 50 | in: body 51 | description: Pet to add to the store 52 | required: true 53 | schema: 54 | $ref: 'NewPet.yaml' 55 | responses: 56 | "200": 57 | description: pet response 58 | schema: 59 | $ref: 'Pet.yaml' 60 | default: 61 | description: unexpected error 62 | schema: 63 | $ref: '../common/Error.yaml' 64 | /pets/{id}: 65 | get: 66 | description: Returns a user based on a single ID, if the user does not have access to the pet 67 | operationId: find pet by id 68 | parameters: 69 | - name: id 70 | in: path 71 | description: ID of pet to fetch 72 | required: true 73 | type: integer 74 | format: int64 75 | responses: 76 | "200": 77 | description: pet response 78 | schema: 79 | $ref: 'Pet.yaml' 80 | default: 81 | description: unexpected error 82 | schema: 83 | $ref: '../common/Error.yaml' 84 | delete: 85 | description: deletes a single pet based on the ID supplied 86 | operationId: deletePet 87 | parameters: 88 | - name: id 89 | in: path 90 | description: ID of pet to delete 91 | required: true 92 | type: integer 93 | format: int64 94 | responses: 95 | "204": 96 | description: pet deleted 97 | default: 98 | description: unexpected error 99 | schema: 100 | $ref: '../common/Error.yaml' 101 | -------------------------------------------------------------------------------- /DEVELOPMENT.md: -------------------------------------------------------------------------------- 1 | ## Development Guidelines 2 | 3 | This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Contributor Board will initially follow these processes when merging changes from external contributors or from the TCB itself. This guideline document will be adjusted as practicality dictates. 4 | 5 | ## OAI Specification Driving factors 6 | 7 | The OpenAPI Specification should be use-case driven. We can specify support for hypothetical use cases as we see fit, but specifications should be backed by realistic scenarios. 8 | 9 | ## Specification Change Criteria 10 | 11 | The specification _will change_ from the original 2.0 version. We should typically make changes when any of the following criteria are met: 12 | 13 | - Clarity. The current "way" something is done doesn't make sense, is complicated, or not clear. 14 | - Consistency. A portion of the specification is not consistent with the rest, or with the industry standard terminology. 15 | - Necessary functionality. We are missing functionality because of a certain design of the specification. 16 | - Forward-looking designs. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. 17 | - Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the _common_ and _important_ use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. 18 | 19 | 20 | ## Tracking Process 21 | 22 | - Use GitHub for all spec designs, use cases, and so on. 23 | - As with 2.0, the **human readable** document is the source of truth. If using a JSON Schema again to document the spec, it is secondary to the human documentation. The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example). 24 | - The `master` branch shall remain the current, released OpenAPI Specification (i.e., 2.0). We will work in an OpenAPI.next branch, which shall be described and linked to on the **default** README.md on master. 25 | - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. 26 | - New features should be done in feature branches which, upon approval, are merged into the OpenAPI.next branch. 27 | - Use labels for the workflow of specification changes. Examples of labels are `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, and `needs approval`. These labels must be assigned by project committers. 28 | - An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. 29 | - A PR will be used to describe the _proposed_ solution, and linked to the original issue. 30 | - Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. 31 | - When the OpenApi.next spec is complete and approved for release, the branch will be merged to master. 32 | 33 | ## Approving Changes 34 | 35 | For each change in the specification we should _always_ consider the following: 36 | 37 | - Migration. Is this a construct that has a path from the existing 2.0 specification? If so, how complicated is it to migrate to the proposed change? 38 | - Tooling. Strive to support code generation, software interfaces, and spec generation techniques. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. 39 | - Visualization. Can the specification change be graphically visualized somehow in a UI or other interface? 40 | 41 | Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @fehguy". After voting criteria is met, any committer can merge the PR. (**TODO**: we will want to formalize what voting criteria actually is). 42 | 43 | No change should be approved until there is documentation for it, supplied in an accompanying PR. 44 | 45 | ## Transparency 46 | 47 | We should always be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. 48 | 49 | - Asynchronous discussions should live in the GitHub issues for this project. 50 | - Realtime discussions should be in a public chat such as IRC or Slack. 51 | 52 | -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-simple.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | swagger: "2.0" 3 | info: 4 | version: "1.0.0" 5 | title: "Swagger Petstore" 6 | description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" 7 | termsOfService: "http://swagger.io/terms/" 8 | contact: 9 | name: "Swagger API Team" 10 | license: 11 | name: "MIT" 12 | host: "petstore.swagger.io" 13 | basePath: "/api" 14 | schemes: 15 | - "http" 16 | consumes: 17 | - "application/json" 18 | produces: 19 | - "application/json" 20 | paths: 21 | /pets: 22 | get: 23 | description: "Returns all pets from the system that the user has access to" 24 | operationId: "findPets" 25 | produces: 26 | - "application/json" 27 | - "application/xml" 28 | - "text/xml" 29 | - "text/html" 30 | parameters: 31 | - 32 | name: "tags" 33 | in: "query" 34 | description: "tags to filter by" 35 | required: false 36 | type: "array" 37 | items: 38 | type: "string" 39 | collectionFormat: "csv" 40 | - 41 | name: "limit" 42 | in: "query" 43 | description: "maximum number of results to return" 44 | required: false 45 | type: "integer" 46 | format: "int32" 47 | responses: 48 | "200": 49 | description: "pet response" 50 | schema: 51 | type: "array" 52 | items: 53 | $ref: "#/definitions/Pet" 54 | default: 55 | description: "unexpected error" 56 | schema: 57 | $ref: "#/definitions/ErrorModel" 58 | post: 59 | description: "Creates a new pet in the store. Duplicates are allowed" 60 | operationId: "addPet" 61 | produces: 62 | - "application/json" 63 | parameters: 64 | - 65 | name: "pet" 66 | in: "body" 67 | description: "Pet to add to the store" 68 | required: true 69 | schema: 70 | $ref: "#/definitions/NewPet" 71 | responses: 72 | "200": 73 | description: "pet response" 74 | schema: 75 | $ref: "#/definitions/Pet" 76 | default: 77 | description: "unexpected error" 78 | schema: 79 | $ref: "#/definitions/ErrorModel" 80 | /pets/{id}: 81 | get: 82 | description: "Returns a user based on a single ID, if the user does not have access to the pet" 83 | operationId: "findPetById" 84 | produces: 85 | - "application/json" 86 | - "application/xml" 87 | - "text/xml" 88 | - "text/html" 89 | parameters: 90 | - 91 | name: "id" 92 | in: "path" 93 | description: "ID of pet to fetch" 94 | required: true 95 | type: "integer" 96 | format: "int64" 97 | responses: 98 | "200": 99 | description: "pet response" 100 | schema: 101 | $ref: "#/definitions/Pet" 102 | default: 103 | description: "unexpected error" 104 | schema: 105 | $ref: "#/definitions/ErrorModel" 106 | delete: 107 | description: "deletes a single pet based on the ID supplied" 108 | operationId: "deletePet" 109 | parameters: 110 | - 111 | name: "id" 112 | in: "path" 113 | description: "ID of pet to delete" 114 | required: true 115 | type: "integer" 116 | format: "int64" 117 | responses: 118 | "204": 119 | description: "pet deleted" 120 | default: 121 | description: "unexpected error" 122 | schema: 123 | $ref: "#/definitions/ErrorModel" 124 | definitions: 125 | Pet: 126 | type: "object" 127 | allOf: 128 | - 129 | $ref: "#/definitions/NewPet" 130 | - 131 | required: 132 | - "id" 133 | properties: 134 | id: 135 | type: "integer" 136 | format: "int64" 137 | NewPet: 138 | type: "object" 139 | required: 140 | - "name" 141 | properties: 142 | name: 143 | type: "string" 144 | tag: 145 | type: "string" 146 | ErrorModel: 147 | type: "object" 148 | required: 149 | - "code" 150 | - "message" 151 | properties: 152 | code: 153 | type: "integer" 154 | format: "int32" 155 | message: 156 | type: "string" 157 | 158 | -------------------------------------------------------------------------------- /schemas/v1.2/dataType.json: -------------------------------------------------------------------------------- 1 | { 2 | "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataType.json#", 3 | "$schema": "http://json-schema.org/draft-04/schema#", 4 | "description": "Data type as described by the specification (version 1.2)", 5 | "type": "object", 6 | "oneOf": [ 7 | { "$ref": "#/definitions/refType" }, 8 | { "$ref": "#/definitions/voidType" }, 9 | { "$ref": "#/definitions/primitiveType" }, 10 | { "$ref": "#/definitions/modelType" }, 11 | { "$ref": "#/definitions/arrayType" } 12 | ], 13 | "definitions": { 14 | "refType": { 15 | "required": [ "$ref" ], 16 | "properties": { 17 | "$ref": { "type": "string" } 18 | }, 19 | "additionalProperties": false 20 | }, 21 | "voidType": { 22 | "enum": [ { "type": "void" } ] 23 | }, 24 | "modelType": { 25 | "required": [ "type" ], 26 | "properties": { 27 | "type": { 28 | "type": "string", 29 | "not": { 30 | "enum": [ "boolean", "integer", "number", "string", "array" ] 31 | } 32 | } 33 | }, 34 | "additionalProperties": false 35 | }, 36 | "primitiveType": { 37 | "required": [ "type" ], 38 | "properties": { 39 | "type": { 40 | "enum": [ "boolean", "integer", "number", "string" ] 41 | }, 42 | "format": { "type": "string" }, 43 | "defaultValue": { 44 | "not": { "type": [ "array", "object", "null" ] } 45 | }, 46 | "enum": { 47 | "type": "array", 48 | "items": { "type": "string" }, 49 | "minItems": 1, 50 | "uniqueItems": true 51 | }, 52 | "minimum": { "type": "string" }, 53 | "maximum": { "type": "string" } 54 | }, 55 | "additionalProperties": false, 56 | "dependencies": { 57 | "format": { 58 | "oneOf": [ 59 | { 60 | "properties": { 61 | "type": { "enum": [ "integer" ] }, 62 | "format": { "enum": [ "int32", "int64" ] } 63 | } 64 | }, 65 | { 66 | "properties": { 67 | "type": { "enum": [ "number" ] }, 68 | "format": { "enum": [ "float", "double" ] } 69 | } 70 | }, 71 | { 72 | "properties": { 73 | "type": { "enum": [ "string" ] }, 74 | "format": { 75 | "enum": [ "byte", "date", "date-time" ] 76 | } 77 | } 78 | } 79 | ] 80 | }, 81 | "enum": { 82 | "properties": { 83 | "type": { "enum": [ "string" ] } 84 | } 85 | }, 86 | "minimum": { 87 | "properties": { 88 | "type": { "enum": [ "integer", "number" ] } 89 | } 90 | }, 91 | "maximum": { 92 | "properties": { 93 | "type": { "enum": [ "integer", "number" ] } 94 | } 95 | } 96 | } 97 | }, 98 | "arrayType": { 99 | "required": [ "type", "items" ], 100 | "properties": { 101 | "type": { "enum": [ "array" ] }, 102 | "items": { 103 | "type": "array", 104 | "items": { "$ref": "#/definitions/itemsObject" } 105 | }, 106 | "uniqueItems": { "type": "boolean" } 107 | }, 108 | "additionalProperties": false 109 | }, 110 | "itemsObject": { 111 | "oneOf": [ 112 | { 113 | "$ref": "#/definitions/refType" 114 | }, 115 | { 116 | "allOf": [ 117 | { 118 | "$ref": "#/definitions/primitiveType" 119 | }, 120 | { 121 | "properties": { 122 | "type": {}, 123 | "format": {} 124 | }, 125 | "additionalProperties": false 126 | } 127 | ] 128 | } 129 | ] 130 | } 131 | } 132 | } -------------------------------------------------------------------------------- /examples/v2.0/json/api-with-examples.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "title": "Simple API overview", 5 | "version": "v2" 6 | }, 7 | "paths": { 8 | "/": { 9 | "get": { 10 | "operationId": "listVersionsv2", 11 | "summary": "List API versions", 12 | "produces": [ 13 | "application/json" 14 | ], 15 | "responses": { 16 | "200": { 17 | "description": "200 300 response", 18 | "examples": { 19 | "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" 20 | } 21 | }, 22 | "300": { 23 | "description": "200 300 response", 24 | "examples": { 25 | "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" 26 | } 27 | } 28 | } 29 | } 30 | }, 31 | "/v2": { 32 | "get": { 33 | "operationId": "getVersionDetailsv2", 34 | "summary": "Show API version details", 35 | "produces": [ 36 | "application/json" 37 | ], 38 | "responses": { 39 | "200": { 40 | "description": "200 203 response", 41 | "examples": { 42 | "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" 43 | } 44 | }, 45 | "203": { 46 | "description": "200 203 response", 47 | "examples": { 48 | "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://23.253.228.211:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" 49 | } 50 | } 51 | } 52 | } 53 | } 54 | }, 55 | "consumes": [ 56 | "application/json" 57 | ] 58 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/petstore-with-external-docs.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | swagger: "2.0" 3 | info: 4 | version: "1.0.0" 5 | title: "Swagger Petstore" 6 | description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" 7 | termsOfService: "http://swagger.io/terms/" 8 | contact: 9 | name: "Swagger API Team" 10 | email: "apiteam@swagger.io" 11 | url: "http://swagger.io" 12 | license: 13 | name: "MIT" 14 | url: "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT" 15 | externalDocs: 16 | description: "find more info here" 17 | url: "https://swagger.io/about" 18 | host: "petstore.swagger.io" 19 | basePath: "/api" 20 | schemes: 21 | - "http" 22 | consumes: 23 | - "application/json" 24 | produces: 25 | - "application/json" 26 | paths: 27 | /pets: 28 | get: 29 | description: "Returns all pets from the system that the user has access to" 30 | operationId: "findPets" 31 | externalDocs: 32 | description: "find more info here" 33 | url: "https://swagger.io/about" 34 | produces: 35 | - "application/json" 36 | - "application/xml" 37 | - "text/xml" 38 | - "text/html" 39 | parameters: 40 | - 41 | name: "tags" 42 | in: "query" 43 | description: "tags to filter by" 44 | required: false 45 | type: "array" 46 | items: 47 | type: "string" 48 | collectionFormat: "csv" 49 | - 50 | name: "limit" 51 | in: "query" 52 | description: "maximum number of results to return" 53 | required: false 54 | type: "integer" 55 | format: "int32" 56 | responses: 57 | "200": 58 | description: "pet response" 59 | schema: 60 | type: "array" 61 | items: 62 | $ref: "#/definitions/Pet" 63 | default: 64 | description: "unexpected error" 65 | schema: 66 | $ref: "#/definitions/ErrorModel" 67 | post: 68 | description: "Creates a new pet in the store. Duplicates are allowed" 69 | operationId: "addPet" 70 | produces: 71 | - "application/json" 72 | parameters: 73 | - 74 | name: "pet" 75 | in: "body" 76 | description: "Pet to add to the store" 77 | required: true 78 | schema: 79 | $ref: "#/definitions/NewPet" 80 | responses: 81 | "200": 82 | description: "pet response" 83 | schema: 84 | $ref: "#/definitions/Pet" 85 | default: 86 | description: "unexpected error" 87 | schema: 88 | $ref: "#/definitions/ErrorModel" 89 | /pets/{id}: 90 | get: 91 | description: "Returns a user based on a single ID, if the user does not have access to the pet" 92 | operationId: "findPetById" 93 | produces: 94 | - "application/json" 95 | - "application/xml" 96 | - "text/xml" 97 | - "text/html" 98 | parameters: 99 | - 100 | name: "id" 101 | in: "path" 102 | description: "ID of pet to fetch" 103 | required: true 104 | type: "integer" 105 | format: "int64" 106 | responses: 107 | "200": 108 | description: "pet response" 109 | schema: 110 | $ref: "#/definitions/Pet" 111 | default: 112 | description: "unexpected error" 113 | schema: 114 | $ref: "#/definitions/ErrorModel" 115 | delete: 116 | description: "deletes a single pet based on the ID supplied" 117 | operationId: "deletePet" 118 | parameters: 119 | - 120 | name: "id" 121 | in: "path" 122 | description: "ID of pet to delete" 123 | required: true 124 | type: "integer" 125 | format: "int64" 126 | responses: 127 | "204": 128 | description: "pet deleted" 129 | default: 130 | description: "unexpected error" 131 | schema: 132 | $ref: "#/definitions/ErrorModel" 133 | definitions: 134 | Pet: 135 | type: "object" 136 | allOf: 137 | - 138 | $ref: "#/definitions/NewPet" 139 | - 140 | required: 141 | - "id" 142 | properties: 143 | id: 144 | type: "integer" 145 | format: "int64" 146 | NewPet: 147 | type: "object" 148 | required: 149 | - "name" 150 | properties: 151 | name: 152 | type: "string" 153 | tag: 154 | type: "string" 155 | ErrorModel: 156 | type: "object" 157 | required: 158 | - "code" 159 | - "message" 160 | properties: 161 | code: 162 | type: "integer" 163 | format: "int32" 164 | message: 165 | type: "string" 166 | 167 | -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-separate/spec/swagger.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://helloreverb.com/terms/", 8 | "contact": { 9 | "name": "Wordnik API Team", 10 | "email": "foo@example.com", 11 | "url": "http://madskristensen.net" 12 | }, 13 | "license": { 14 | "name": "MIT", 15 | "url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT" 16 | } 17 | }, 18 | "host": "petstore.swagger.wordnik.com", 19 | "basePath": "/api", 20 | "schemes": [ 21 | "http" 22 | ], 23 | "consumes": [ 24 | "application/json" 25 | ], 26 | "produces": [ 27 | "application/json" 28 | ], 29 | "paths": { 30 | "/pets": { 31 | "get": { 32 | "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", 33 | "operationId": "findPets", 34 | "parameters": [ 35 | { 36 | "$ref": "parameters.json#/tagsParam" 37 | }, 38 | { 39 | "$ref": "parameters.json#/limitsParam" 40 | } 41 | ], 42 | "responses": { 43 | "200": { 44 | "description": "pet response", 45 | "schema": { 46 | "type": "array", 47 | "items": { 48 | "$ref": "Pet.json" 49 | } 50 | } 51 | }, 52 | "default": { 53 | "description": "unexpected error", 54 | "schema": { 55 | "$ref": "../common/Error.json" 56 | } 57 | } 58 | } 59 | }, 60 | "post": { 61 | "description": "Creates a new pet in the store. Duplicates are allowed", 62 | "operationId": "addPet", 63 | "parameters": [ 64 | { 65 | "name": "pet", 66 | "in": "body", 67 | "description": "Pet to add to the store", 68 | "required": true, 69 | "schema": { 70 | "$ref": "NewPet.json" 71 | } 72 | } 73 | ], 74 | "responses": { 75 | "200": { 76 | "description": "pet response", 77 | "schema": { 78 | "$ref": "Pet.json" 79 | } 80 | }, 81 | "default": { 82 | "description": "unexpected error", 83 | "schema": { 84 | "$ref": "../common/Error.json" 85 | } 86 | } 87 | } 88 | } 89 | }, 90 | "/pets/{id}": { 91 | "get": { 92 | "description": "Returns a user based on a single ID, if the user does not have access to the pet", 93 | "operationId": "find pet by id", 94 | "parameters": [ 95 | { 96 | "name": "id", 97 | "in": "path", 98 | "description": "ID of pet to fetch", 99 | "required": true, 100 | "type": "integer", 101 | "format": "int64" 102 | } 103 | ], 104 | "responses": { 105 | "200": { 106 | "description": "pet response", 107 | "schema": { 108 | "$ref": "Pet.json" 109 | } 110 | }, 111 | "default": { 112 | "description": "unexpected error", 113 | "schema": { 114 | "$ref": "../common/Error.json" 115 | } 116 | } 117 | } 118 | }, 119 | "delete": { 120 | "description": "deletes a single pet based on the ID supplied", 121 | "operationId": "deletePet", 122 | "parameters": [ 123 | { 124 | "name": "id", 125 | "in": "path", 126 | "description": "ID of pet to delete", 127 | "required": true, 128 | "type": "integer", 129 | "format": "int64" 130 | } 131 | ], 132 | "responses": { 133 | "204": { 134 | "description": "pet deleted" 135 | }, 136 | "default": { 137 | "description": "unexpected error", 138 | "schema": { 139 | "$ref": "../common/Error.json" 140 | } 141 | } 142 | } 143 | } 144 | } 145 | } 146 | } -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The OpenAPI Specification 2 | 3 | [![Build Status](https://travis-ci.org/OAI/OpenAPI-Specification.svg?branch=master)](https://travis-ci.org/OAI/OpenAPI-Specification) 4 | 5 | ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) 6 | 7 | 8 | # Note 9 | 10 | This is not an active work branch anymore but is currently kept around. For details on how to contribute next, review our [Development Guidelines](https://github.com/OAI/OpenAPI-Specification/blob/master/DEVELOPMENT.md). 11 | 12 | 13 | 14 | --- 15 | 16 | 17 | The OpenAPI Specification is a community driven, open specification within the [Open API Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. 18 | 19 | The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. 20 | 21 | Use cases for machine-readable API definition documents include, but are not limited to, interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an API's services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application. 22 | 23 | The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service—the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI—this specification is not intended to cover every possible style of REST APIs. The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API. 24 | 25 | This GitHub project is the starting point for OpenAPI. 26 | Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project. 27 | 28 | ## Current Version - 3.0 29 | 30 | The current version of the OpenAPI specification is [OpenAPI Specification 3.0](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md). 31 | 32 | ### Previous Versions 33 | 34 | This repository also contains the [OpenAPI Specification 2.0](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/2.0), which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, 35 | as well as the Swagger 1.2 and Swagger 2.0 specifications. 36 | 37 | Each folder in this repository, such as [examples](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/examples) and [schemas](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/schemas), should contain folders pertaining to the current and previous versions of the specification. 38 | 39 | ## See It in Action 40 | 41 | If you just want to see it work, check out the [list of current examples](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/examples/v3.0). 42 | 43 | ## Tools and Libraries 44 | 45 | Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing 46 | [list of 3.0 Implementations](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/IMPLEMENTATIONS.md). 47 | 48 | ## Participation 49 | 50 | The current process for development of the OpenAPI Specification is described in 51 | [Development Guidelines](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md). 52 | Development of the next version of the OpenAPI Specification is guided by the [Technical Developer Community](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master. 53 | 54 | The Open API Initiative encourages participation from individuals and companies alike. 55 | If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: 56 | 57 | * Review the [current specification](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md). The human-readable markdown file _is the source of truth_ for the specification. 58 | * Review the [development](https://github.com/SmartAPI/smartAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md) process so you understand how the spec is evolving. 59 | * Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by adding a comment to the existing issue or PR. 60 | * Create an issue to describe a new concern. If possible, propose a solution. 61 | 62 | Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification. 63 | 64 | ## License 65 | 66 | 67 | See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE) 68 | 69 | 70 | ![Analytics](https://ga-beacon.appspot.com/UA-831873-42/readme.md?pixel) 71 | -------------------------------------------------------------------------------- /examples/v3.0/petstore-expanded.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | version: 1.0.0 4 | title: Swagger Petstore 5 | description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification 6 | termsOfService: http://swagger.io/terms/ 7 | contact: 8 | name: Swagger API Team 9 | email: foo@example.com 10 | url: http://madskristensen.net 11 | license: 12 | name: MIT 13 | url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT 14 | servers: 15 | - url: http://petstore.swagger.io/api 16 | paths: 17 | /pets: 18 | get: 19 | description: | 20 | Returns all pets from the system that the user has access to 21 | Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. 22 | 23 | Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. 24 | operationId: findPets 25 | parameters: 26 | - name: tags 27 | in: query 28 | description: tags to filter by 29 | required: false 30 | style: form 31 | schema: 32 | type: array 33 | items: 34 | type: string 35 | - name: limit 36 | in: query 37 | description: maximum number of results to return 38 | required: false 39 | schema: 40 | type: integer 41 | format: int32 42 | responses: 43 | 200: 44 | description: pet response 45 | content: 46 | application/json: 47 | schema: 48 | type: array 49 | items: 50 | $ref: '#/components/schemas/Pet' 51 | default: 52 | description: unexpected error 53 | content: 54 | application/json: 55 | schema: 56 | $ref: '#/components/schemas/Error' 57 | post: 58 | description: Creates a new pet in the store. Duplicates are allowed 59 | operationId: addPet 60 | requestBody: 61 | description: Pet to add to the store 62 | required: true 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/NewPet' 67 | responses: 68 | 200: 69 | description: pet response 70 | content: 71 | application/json: 72 | schema: 73 | $ref: '#/components/schemas/Pet' 74 | default: 75 | description: unexpected error 76 | content: 77 | application/json: 78 | schema: 79 | $ref: '#/components/schemas/Error' 80 | /pets/{id}: 81 | get: 82 | description: Returns a user based on a single ID, if the user does not have access to the pet 83 | operationId: find pet by id 84 | parameters: 85 | - name: id 86 | in: path 87 | description: ID of pet to fetch 88 | required: true 89 | schema: 90 | type: integer 91 | format: int64 92 | responses: 93 | 200: 94 | description: pet response 95 | content: 96 | application/json: 97 | schema: 98 | $ref: '#/components/schemas/Pet' 99 | default: 100 | description: unexpected error 101 | content: 102 | application/json: 103 | schema: 104 | $ref: '#/components/schemas/Error' 105 | delete: 106 | description: deletes a single pet based on the ID supplied 107 | operationId: deletePet 108 | parameters: 109 | - name: id 110 | in: path 111 | description: ID of pet to delete 112 | required: true 113 | schema: 114 | type: integer 115 | format: int64 116 | responses: 117 | 204: 118 | description: pet deleted 119 | default: 120 | description: unexpected error 121 | content: 122 | application/json: 123 | schema: 124 | $ref: '#/components/schemas/Error' 125 | components: 126 | schemas: 127 | Pet: 128 | allOf: 129 | - $ref: '#/components/schemas/NewPet' 130 | - required: 131 | - id 132 | properties: 133 | id: 134 | type: integer 135 | format: int64 136 | 137 | NewPet: 138 | required: 139 | - name 140 | properties: 141 | name: 142 | type: string 143 | tag: 144 | type: string 145 | 146 | Error: 147 | required: 148 | - code 149 | - message 150 | properties: 151 | code: 152 | type: integer 153 | format: int32 154 | message: 155 | type: string 156 | -------------------------------------------------------------------------------- /versions/mygene.info.v3.compliant: -------------------------------------------------------------------------------- 1 | openapi: '3.0' 2 | info: 3 | version: 3.0.0.2 4 | title: MyGene.info API 5 | description: >- 6 | Documentation of the MyGene.info Gene Query web services. Learn more about 7 | [MyGene.info](http://mygene.info/) 8 | termsOfService: 'http://example.com/terms/' 9 | contact: 10 | name: Chunlei Wu 11 | x-role: responsible developer 12 | email: help@mygene.info 13 | x-id: 'http://orcid.org/0000-0002-2629-6124' 14 | x-accessRestriction: none 15 | x-maturity: production 16 | x-implementationLanguage: python 17 | externalDocs: 18 | description: Find more info here 19 | url: 'https://example.com' 20 | x-externalResources: 21 | - x-url: 'http://example.org/api/docs' 22 | x-type: api documentation 23 | - x-url: 'https://doi.org/10.1093/nar/gks1114' 24 | x-type: publication 25 | x-description: 'BioGPS and MyGene.info: organizing online, gene-centric information' 26 | - x-url: 'http://twitter.com/mygeneinfo' 27 | x-type: social media 28 | servers: 29 | - url: 'http://mygene.info' 30 | description: Development server 31 | x-location: 'California, USA' 32 | tags: 33 | - x-id: 'http://purl.bioontology.org/ontology/MESH/D005796' 34 | name: Genes 35 | components: 36 | schemas: 37 | Category: 38 | type: object 39 | properties: 40 | id: 41 | type: integer 42 | format: int64 43 | name: 44 | type: string 45 | Tag: 46 | type: object 47 | properties: 48 | id: 49 | type: integer 50 | format: int64 51 | name: 52 | type: string 53 | parameters: 54 | skipParam: 55 | name: skip 56 | in: query 57 | description: number of items to skip 58 | required: true 59 | schema: 60 | type: integer 61 | format: int32 62 | limitParam: 63 | name: limit 64 | in: query 65 | description: max records to return 66 | required: true 67 | schema: 68 | type: integer 69 | format: int32 70 | responses: 71 | NotFound: 72 | description: Entity not found. 73 | IllegalInput: 74 | description: Illegal input for operation. 75 | securitySchemes: 76 | api_key: 77 | type: apiKey 78 | name: api_key 79 | in: header 80 | petstore_auth: 81 | type: oauth2 82 | flows: 83 | implicit: 84 | authorizationUrl: 'http://example.org/api/oauth/dialog' 85 | scopes: 86 | 'write:pets': modify genes in your account 87 | 'read:pets': read your genes 88 | paths: 89 | /query: 90 | get: 91 | tags: 92 | - query 93 | description: Makes gene query and returns matching gene list. 94 | summary: Makes gene query and returns matching gene list. 95 | x-accessRestriction: fee 96 | parameters: 97 | - name: q 98 | in: query 99 | description: >- 100 | Query string. Examples "CDK2", "NM_052827", "204639_at". The 101 | detailed query syntax can be found at 102 | http://docs.mygene.info/en/latest/doc/query_service.html 103 | required: true 104 | schema: 105 | type: string 106 | x-parameterType: InputParameter 107 | x-valueType: 108 | - 'http://identifiers.org/hgnc.symbol' 109 | - 'http://identifiers.org/refseq' 110 | - 'http://identifiers.org/unigene' 111 | - 'http://identifiers.org/uniprot' 112 | - 'http://identifiers.org/pdb' 113 | operationId: add operation id here 114 | responses: 115 | '200': 116 | description: Successful response. 117 | content: 118 | application/json: 119 | x-responseProfile: 'http://www.w3.org/ns/anno.jsonld' 120 | '/gene/{geneid}': 121 | get: 122 | tags: 123 | - gene 124 | parameters: 125 | - name: geneid 126 | in: path 127 | description: >- 128 | Entrez or Ensembl gene id, e.g., 1017, ENSG00000170248. A retired 129 | Entrez Gene id works too if it is replaced by a new one, e.g., 130 | 245794 131 | required: true 132 | x-parameterType: InputParameter 133 | x-valueType: 134 | - 'http://identifiers.org/ncbigene' 135 | - 'http://identifiers.org/ensembl' 136 | x-defaultValue: add default 137 | x-exampleValue: '1017' 138 | operationId: getAnnotation 139 | summary: add summary 140 | responses: 141 | '200': 142 | description: Successful response 143 | content: 144 | application/json: 145 | x-responseSchema: 146 | properties: 147 | reporter: 148 | properties: 149 | HTA-2_0: 150 | type: string 151 | HG-U133_Plus_2: 152 | items: 153 | type: string 154 | type: array 155 | HuEx-1_0: 156 | type: integer 157 | HuGene-1_1: 158 | type: integer 159 | HuGene-2_1: 160 | type: integer 161 | HG-U95Av2: 162 | items: 163 | type: string 164 | type: array 165 | type: object 166 | x-responseValueType: 167 | - path: ec 168 | valueType: 'http://identifiers.org/ec-code/' 169 | - path: ensembl.gene 170 | valueType: 'http://identifiers.org/ensembl/' 171 | - path: ensembl.translation.protein 172 | valueType: 'http://identifiers.org/ensembl/' 173 | - path: ensembl.translation.rna 174 | valueType: 'http://identifiers.org/ensembl/' 175 | - path: entrezgene 176 | valueType: 'http://identifiers.org/ncbigene/' 177 | - path: generif.pubmed 178 | valueType: 'http://identifiers.org/pubmed/' 179 | -------------------------------------------------------------------------------- /examples/v3.0/link-example.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | title: Link Example 4 | version: 1.0.0 5 | paths: 6 | /2.0/users/{username}: 7 | get: 8 | operationId: getUserByName 9 | parameters: 10 | - name: username 11 | in: path 12 | required: true 13 | schema: 14 | type: string 15 | responses: 16 | '200': 17 | description: The User 18 | content: 19 | application/json: 20 | schema: 21 | $ref: '#/components/schemas/user' 22 | links: 23 | userRepositories: 24 | $ref: '#/components/links/UserRepositories' 25 | /2.0/repositories/{username}: 26 | get: 27 | operationId: getRepositoriesByOwner 28 | parameters: 29 | - name: username 30 | in: path 31 | required: true 32 | schema: 33 | type: string 34 | responses: 35 | '200': 36 | description: repositories owned by the supplied user 37 | content: 38 | application/json: 39 | schema: 40 | type: array 41 | items: 42 | $ref: '#/components/schemas/repository' 43 | links: 44 | userRepository: 45 | $ref: '#/components/links/UserRepository' 46 | /2.0/repositories/{username}/{slug}: 47 | get: 48 | operationId: getRepository 49 | parameters: 50 | - name: username 51 | in: path 52 | required: true 53 | schema: 54 | type: string 55 | - name: slug 56 | in: path 57 | required: true 58 | schema: 59 | type: string 60 | responses: 61 | '200': 62 | description: The repository 63 | content: 64 | application/json: 65 | schema: 66 | $ref: '#/components/schemas/repository' 67 | links: 68 | repositoryPullRequests: 69 | $ref: '#/components/links/RepositoryPullRequests' 70 | /2.0/repositories/{username}/{slug}/pullrequests: 71 | get: 72 | operationId: getPullRequestsByRepository 73 | parameters: 74 | - name: username 75 | in: path 76 | required: true 77 | schema: 78 | type: string 79 | - name: slug 80 | in: path 81 | required: true 82 | schema: 83 | type: string 84 | - name: state 85 | in: query 86 | schema: 87 | type: string 88 | enum: 89 | - open 90 | - merged 91 | - declined 92 | responses: 93 | '200': 94 | description: an array of pull request objects 95 | content: 96 | application/json: 97 | schema: 98 | type: array 99 | items: 100 | $ref: '#/components/schemas/pullrequest' 101 | /2.0/repositories/{username}/{slug}/pullrequests/{pid}: 102 | get: 103 | operationId: getPullRequestsById 104 | parameters: 105 | - name: username 106 | in: path 107 | required: true 108 | schema: 109 | type: string 110 | - name: slug 111 | in: path 112 | required: true 113 | schema: 114 | type: string 115 | - name: pid 116 | in: path 117 | required: true 118 | schema: 119 | type: string 120 | responses: 121 | '200': 122 | description: a pull request object 123 | content: 124 | application/json: 125 | schema: 126 | $ref: '#/components/schemas/pullrequest' 127 | links: 128 | pullRequestMerge: 129 | $ref: '#/components/links/PullRequestMerge' 130 | /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: 131 | post: 132 | operationId: mergePullRequest 133 | parameters: 134 | - name: username 135 | in: path 136 | required: true 137 | schema: 138 | type: string 139 | - name: slug 140 | in: path 141 | required: true 142 | schema: 143 | type: string 144 | - name: pid 145 | in: path 146 | required: true 147 | schema: 148 | type: string 149 | responses: 150 | '204': 151 | description: the PR was successfully merged 152 | components: 153 | links: 154 | UserRepositories: 155 | # returns array of '#/components/schemas/repository' 156 | operationId: getRepositoriesByOwner 157 | parameters: 158 | username: $response.body#/username 159 | UserRepository: 160 | # returns '#/components/schemas/repository' 161 | operationId: getRepository 162 | parameters: 163 | username: $response.body#/owner/username 164 | slug: $response.body#/slug 165 | RepositoryPullRequests: 166 | # returns '#/components/schemas/pullrequest' 167 | operationId: getPullRequestsByRepository 168 | parameters: 169 | username: $response.body#/owner/username 170 | slug: $response.body#/slug 171 | PullRequestMerge: 172 | # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge 173 | operationId: mergePullRequest 174 | parameters: 175 | username: $response.body#/author/username 176 | slug: $response.body#/repository/slug 177 | pid: $response.body#/id 178 | schemas: 179 | user: 180 | type: object 181 | properties: 182 | username: 183 | type: string 184 | uuid: 185 | type: string 186 | repository: 187 | type: object 188 | properties: 189 | slug: 190 | type: string 191 | owner: 192 | $ref: '#/components/schemas/user' 193 | pullrequest: 194 | type: object 195 | properties: 196 | id: 197 | type: integer 198 | title: 199 | type: string 200 | repository: 201 | $ref: '#/components/schemas/repository' 202 | author: 203 | $ref: '#/components/schemas/user' 204 | -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-simple.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team" 10 | }, 11 | "license": { 12 | "name": "MIT" 13 | } 14 | }, 15 | "host": "petstore.swagger.io", 16 | "basePath": "/api", 17 | "schemes": [ 18 | "http" 19 | ], 20 | "consumes": [ 21 | "application/json" 22 | ], 23 | "produces": [ 24 | "application/json" 25 | ], 26 | "paths": { 27 | "/pets": { 28 | "get": { 29 | "description": "Returns all pets from the system that the user has access to", 30 | "operationId": "findPets", 31 | "produces": [ 32 | "application/json", 33 | "application/xml", 34 | "text/xml", 35 | "text/html" 36 | ], 37 | "parameters": [ 38 | { 39 | "name": "tags", 40 | "in": "query", 41 | "description": "tags to filter by", 42 | "required": false, 43 | "type": "array", 44 | "items": { 45 | "type": "string" 46 | }, 47 | "collectionFormat": "csv" 48 | }, 49 | { 50 | "name": "limit", 51 | "in": "query", 52 | "description": "maximum number of results to return", 53 | "required": false, 54 | "type": "integer", 55 | "format": "int32" 56 | } 57 | ], 58 | "responses": { 59 | "200": { 60 | "description": "pet response", 61 | "schema": { 62 | "type": "array", 63 | "items": { 64 | "$ref": "#/definitions/Pet" 65 | } 66 | } 67 | }, 68 | "default": { 69 | "description": "unexpected error", 70 | "schema": { 71 | "$ref": "#/definitions/ErrorModel" 72 | } 73 | } 74 | } 75 | }, 76 | "post": { 77 | "description": "Creates a new pet in the store. Duplicates are allowed", 78 | "operationId": "addPet", 79 | "produces": [ 80 | "application/json" 81 | ], 82 | "parameters": [ 83 | { 84 | "name": "pet", 85 | "in": "body", 86 | "description": "Pet to add to the store", 87 | "required": true, 88 | "schema": { 89 | "$ref": "#/definitions/NewPet" 90 | } 91 | } 92 | ], 93 | "responses": { 94 | "200": { 95 | "description": "pet response", 96 | "schema": { 97 | "$ref": "#/definitions/Pet" 98 | } 99 | }, 100 | "default": { 101 | "description": "unexpected error", 102 | "schema": { 103 | "$ref": "#/definitions/ErrorModel" 104 | } 105 | } 106 | } 107 | } 108 | }, 109 | "/pets/{id}": { 110 | "get": { 111 | "description": "Returns a user based on a single ID, if the user does not have access to the pet", 112 | "operationId": "findPetById", 113 | "produces": [ 114 | "application/json", 115 | "application/xml", 116 | "text/xml", 117 | "text/html" 118 | ], 119 | "parameters": [ 120 | { 121 | "name": "id", 122 | "in": "path", 123 | "description": "ID of pet to fetch", 124 | "required": true, 125 | "type": "integer", 126 | "format": "int64" 127 | } 128 | ], 129 | "responses": { 130 | "200": { 131 | "description": "pet response", 132 | "schema": { 133 | "$ref": "#/definitions/Pet" 134 | } 135 | }, 136 | "default": { 137 | "description": "unexpected error", 138 | "schema": { 139 | "$ref": "#/definitions/ErrorModel" 140 | } 141 | } 142 | } 143 | }, 144 | "delete": { 145 | "description": "deletes a single pet based on the ID supplied", 146 | "operationId": "deletePet", 147 | "parameters": [ 148 | { 149 | "name": "id", 150 | "in": "path", 151 | "description": "ID of pet to delete", 152 | "required": true, 153 | "type": "integer", 154 | "format": "int64" 155 | } 156 | ], 157 | "responses": { 158 | "204": { 159 | "description": "pet deleted" 160 | }, 161 | "default": { 162 | "description": "unexpected error", 163 | "schema": { 164 | "$ref": "#/definitions/ErrorModel" 165 | } 166 | } 167 | } 168 | } 169 | } 170 | }, 171 | "definitions": { 172 | "Pet": { 173 | "type": "object", 174 | "allOf": [ 175 | { 176 | "$ref": "#/definitions/NewPet" 177 | }, 178 | { 179 | "required": [ 180 | "id" 181 | ], 182 | "properties": { 183 | "id": { 184 | "type": "integer", 185 | "format": "int64" 186 | } 187 | } 188 | } 189 | ] 190 | }, 191 | "NewPet": { 192 | "type": "object", 193 | "required": [ 194 | "name" 195 | ], 196 | "properties": { 197 | "name": { 198 | "type": "string" 199 | }, 200 | "tag": { 201 | "type": "string" 202 | } 203 | } 204 | }, 205 | "ErrorModel": { 206 | "type": "object", 207 | "required": [ 208 | "code", 209 | "message" 210 | ], 211 | "properties": { 212 | "code": { 213 | "type": "integer", 214 | "format": "int32" 215 | }, 216 | "message": { 217 | "type": "string" 218 | } 219 | } 220 | } 221 | } 222 | } -------------------------------------------------------------------------------- /examples/v2.0/json/petstore-with-external-docs.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "version": "1.0.0", 5 | "title": "Swagger Petstore", 6 | "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 7 | "termsOfService": "http://swagger.io/terms/", 8 | "contact": { 9 | "name": "Swagger API Team", 10 | "email": "apiteam@swagger.io", 11 | "url": "http://swagger.io" 12 | }, 13 | "license": { 14 | "name": "MIT", 15 | "url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT" 16 | } 17 | }, 18 | "externalDocs": { 19 | "description": "find more info here", 20 | "url": "https://swagger.io/about" 21 | }, 22 | "host": "petstore.swagger.io", 23 | "basePath": "/api", 24 | "schemes": [ 25 | "http" 26 | ], 27 | "consumes": [ 28 | "application/json" 29 | ], 30 | "produces": [ 31 | "application/json" 32 | ], 33 | "paths": { 34 | "/pets": { 35 | "get": { 36 | "description": "Returns all pets from the system that the user has access to", 37 | "operationId": "findPets", 38 | "externalDocs": { 39 | "description": "find more info here", 40 | "url": "https://swagger.io/about" 41 | }, 42 | "produces": [ 43 | "application/json", 44 | "application/xml", 45 | "text/xml", 46 | "text/html" 47 | ], 48 | "parameters": [ 49 | { 50 | "name": "tags", 51 | "in": "query", 52 | "description": "tags to filter by", 53 | "required": false, 54 | "type": "array", 55 | "items": { 56 | "type": "string" 57 | }, 58 | "collectionFormat": "csv" 59 | }, 60 | { 61 | "name": "limit", 62 | "in": "query", 63 | "description": "maximum number of results to return", 64 | "required": false, 65 | "type": "integer", 66 | "format": "int32" 67 | } 68 | ], 69 | "responses": { 70 | "200": { 71 | "description": "pet response", 72 | "schema": { 73 | "type": "array", 74 | "items": { 75 | "$ref": "#/definitions/Pet" 76 | } 77 | } 78 | }, 79 | "default": { 80 | "description": "unexpected error", 81 | "schema": { 82 | "$ref": "#/definitions/ErrorModel" 83 | } 84 | } 85 | } 86 | }, 87 | "post": { 88 | "description": "Creates a new pet in the store. Duplicates are allowed", 89 | "operationId": "addPet", 90 | "produces": [ 91 | "application/json" 92 | ], 93 | "parameters": [ 94 | { 95 | "name": "pet", 96 | "in": "body", 97 | "description": "Pet to add to the store", 98 | "required": true, 99 | "schema": { 100 | "$ref": "#/definitions/NewPet" 101 | } 102 | } 103 | ], 104 | "responses": { 105 | "200": { 106 | "description": "pet response", 107 | "schema": { 108 | "$ref": "#/definitions/Pet" 109 | } 110 | }, 111 | "default": { 112 | "description": "unexpected error", 113 | "schema": { 114 | "$ref": "#/definitions/ErrorModel" 115 | } 116 | } 117 | } 118 | } 119 | }, 120 | "/pets/{id}": { 121 | "get": { 122 | "description": "Returns a user based on a single ID, if the user does not have access to the pet", 123 | "operationId": "findPetById", 124 | "produces": [ 125 | "application/json", 126 | "application/xml", 127 | "text/xml", 128 | "text/html" 129 | ], 130 | "parameters": [ 131 | { 132 | "name": "id", 133 | "in": "path", 134 | "description": "ID of pet to fetch", 135 | "required": true, 136 | "type": "integer", 137 | "format": "int64" 138 | } 139 | ], 140 | "responses": { 141 | "200": { 142 | "description": "pet response", 143 | "schema": { 144 | "$ref": "#/definitions/Pet" 145 | } 146 | }, 147 | "default": { 148 | "description": "unexpected error", 149 | "schema": { 150 | "$ref": "#/definitions/ErrorModel" 151 | } 152 | } 153 | } 154 | }, 155 | "delete": { 156 | "description": "deletes a single pet based on the ID supplied", 157 | "operationId": "deletePet", 158 | "parameters": [ 159 | { 160 | "name": "id", 161 | "in": "path", 162 | "description": "ID of pet to delete", 163 | "required": true, 164 | "type": "integer", 165 | "format": "int64" 166 | } 167 | ], 168 | "responses": { 169 | "204": { 170 | "description": "pet deleted" 171 | }, 172 | "default": { 173 | "description": "unexpected error", 174 | "schema": { 175 | "$ref": "#/definitions/ErrorModel" 176 | } 177 | } 178 | } 179 | } 180 | } 181 | }, 182 | "definitions": { 183 | "Pet": { 184 | "type": "object", 185 | "allOf": [ 186 | { 187 | "$ref": "#/definitions/NewPet" 188 | }, 189 | { 190 | "required": [ 191 | "id" 192 | ], 193 | "properties": { 194 | "id": { 195 | "type": "integer", 196 | "format": "int64" 197 | } 198 | } 199 | } 200 | ] 201 | }, 202 | "NewPet": { 203 | "type": "object", 204 | "required": [ 205 | "name" 206 | ], 207 | "properties": { 208 | "name": { 209 | "type": "string" 210 | }, 211 | "tag": { 212 | "type": "string" 213 | } 214 | } 215 | }, 216 | "ErrorModel": { 217 | "type": "object", 218 | "required": [ 219 | "code", 220 | "message" 221 | ], 222 | "properties": { 223 | "code": { 224 | "type": "integer", 225 | "format": "int32" 226 | }, 227 | "message": { 228 | "type": "string" 229 | } 230 | } 231 | } 232 | } 233 | } -------------------------------------------------------------------------------- /examples/v2.0/yaml/api-with-examples.yaml: -------------------------------------------------------------------------------- 1 | swagger: "2.0" 2 | info: 3 | title: Simple API overview 4 | version: v2 5 | paths: 6 | /: 7 | get: 8 | operationId: listVersionsv2 9 | summary: List API versions 10 | produces: 11 | - application/json 12 | responses: 13 | "200": 14 | description: |- 15 | 200 300 response 16 | examples: 17 | application/json: |- 18 | { 19 | "versions": [ 20 | { 21 | "status": "CURRENT", 22 | "updated": "2011-01-21T11:33:21Z", 23 | "id": "v2.0", 24 | "links": [ 25 | { 26 | "href": "http://127.0.0.1:8774/v2/", 27 | "rel": "self" 28 | } 29 | ] 30 | }, 31 | { 32 | "status": "EXPERIMENTAL", 33 | "updated": "2013-07-23T11:33:21Z", 34 | "id": "v3.0", 35 | "links": [ 36 | { 37 | "href": "http://127.0.0.1:8774/v3/", 38 | "rel": "self" 39 | } 40 | ] 41 | } 42 | ] 43 | } 44 | "300": 45 | description: |- 46 | 200 300 response 47 | examples: 48 | application/json: |- 49 | { 50 | "versions": [ 51 | { 52 | "status": "CURRENT", 53 | "updated": "2011-01-21T11:33:21Z", 54 | "id": "v2.0", 55 | "links": [ 56 | { 57 | "href": "http://127.0.0.1:8774/v2/", 58 | "rel": "self" 59 | } 60 | ] 61 | }, 62 | { 63 | "status": "EXPERIMENTAL", 64 | "updated": "2013-07-23T11:33:21Z", 65 | "id": "v3.0", 66 | "links": [ 67 | { 68 | "href": "http://127.0.0.1:8774/v3/", 69 | "rel": "self" 70 | } 71 | ] 72 | } 73 | ] 74 | } 75 | /v2: 76 | get: 77 | operationId: getVersionDetailsv2 78 | summary: Show API version details 79 | produces: 80 | - application/json 81 | responses: 82 | "200": 83 | description: |- 84 | 200 203 response 85 | examples: 86 | application/json: |- 87 | { 88 | "version": { 89 | "status": "CURRENT", 90 | "updated": "2011-01-21T11:33:21Z", 91 | "media-types": [ 92 | { 93 | "base": "application/xml", 94 | "type": "application/vnd.openstack.compute+xml;version=2" 95 | }, 96 | { 97 | "base": "application/json", 98 | "type": "application/vnd.openstack.compute+json;version=2" 99 | } 100 | ], 101 | "id": "v2.0", 102 | "links": [ 103 | { 104 | "href": "http://127.0.0.1:8774/v2/", 105 | "rel": "self" 106 | }, 107 | { 108 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 109 | "type": "application/pdf", 110 | "rel": "describedby" 111 | }, 112 | { 113 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 114 | "type": "application/vnd.sun.wadl+xml", 115 | "rel": "describedby" 116 | }, 117 | { 118 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 119 | "type": "application/vnd.sun.wadl+xml", 120 | "rel": "describedby" 121 | } 122 | ] 123 | } 124 | } 125 | "203": 126 | description: |- 127 | 200 203 response 128 | examples: 129 | application/json: |- 130 | { 131 | "version": { 132 | "status": "CURRENT", 133 | "updated": "2011-01-21T11:33:21Z", 134 | "media-types": [ 135 | { 136 | "base": "application/xml", 137 | "type": "application/vnd.openstack.compute+xml;version=2" 138 | }, 139 | { 140 | "base": "application/json", 141 | "type": "application/vnd.openstack.compute+json;version=2" 142 | } 143 | ], 144 | "id": "v2.0", 145 | "links": [ 146 | { 147 | "href": "http://23.253.228.211:8774/v2/", 148 | "rel": "self" 149 | }, 150 | { 151 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 152 | "type": "application/pdf", 153 | "rel": "describedby" 154 | }, 155 | { 156 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 157 | "type": "application/vnd.sun.wadl+xml", 158 | "rel": "describedby" 159 | } 160 | ] 161 | } 162 | } 163 | consumes: 164 | - application/json 165 | -------------------------------------------------------------------------------- /examples/v3.0/api-with-examples.yaml: -------------------------------------------------------------------------------- 1 | openapi: "3.0.0" 2 | info: 3 | title: Simple API overview 4 | version: v2 5 | paths: 6 | /: 7 | get: 8 | operationId: listVersionsv2 9 | summary: List API versions 10 | responses: 11 | 200: 12 | description: |- 13 | 200 response 14 | content: 15 | application/json: 16 | examples: 17 | foo: 18 | value: { 19 | "versions": [ 20 | { 21 | "status": "CURRENT", 22 | "updated": "2011-01-21T11:33:21Z", 23 | "id": "v2.0", 24 | "links": [ 25 | { 26 | "href": "http://127.0.0.1:8774/v2/", 27 | "rel": "self" 28 | } 29 | ] 30 | }, 31 | { 32 | "status": "EXPERIMENTAL", 33 | "updated": "2013-07-23T11:33:21Z", 34 | "id": "v3.0", 35 | "links": [ 36 | { 37 | "href": "http://127.0.0.1:8774/v3/", 38 | "rel": "self" 39 | } 40 | ] 41 | } 42 | ] 43 | } 44 | 300: 45 | description: |- 46 | 300 response 47 | content: 48 | application/json: 49 | examples: 50 | foo: 51 | value: | 52 | { 53 | "versions": [ 54 | { 55 | "status": "CURRENT", 56 | "updated": "2011-01-21T11:33:21Z", 57 | "id": "v2.0", 58 | "links": [ 59 | { 60 | "href": "http://127.0.0.1:8774/v2/", 61 | "rel": "self" 62 | } 63 | ] 64 | }, 65 | { 66 | "status": "EXPERIMENTAL", 67 | "updated": "2013-07-23T11:33:21Z", 68 | "id": "v3.0", 69 | "links": [ 70 | { 71 | "href": "http://127.0.0.1:8774/v3/", 72 | "rel": "self" 73 | } 74 | ] 75 | } 76 | ] 77 | } 78 | /v2: 79 | get: 80 | operationId: getVersionDetailsv2 81 | summary: Show API version details 82 | responses: 83 | 200: 84 | description: |- 85 | 200 response 86 | content: 87 | application/json: 88 | examples: 89 | foo: 90 | value: { 91 | "version": { 92 | "status": "CURRENT", 93 | "updated": "2011-01-21T11:33:21Z", 94 | "media-types": [ 95 | { 96 | "base": "application/xml", 97 | "type": "application/vnd.openstack.compute+xml;version=2" 98 | }, 99 | { 100 | "base": "application/json", 101 | "type": "application/vnd.openstack.compute+json;version=2" 102 | } 103 | ], 104 | "id": "v2.0", 105 | "links": [ 106 | { 107 | "href": "http://127.0.0.1:8774/v2/", 108 | "rel": "self" 109 | }, 110 | { 111 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 112 | "type": "application/pdf", 113 | "rel": "describedby" 114 | }, 115 | { 116 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 117 | "type": "application/vnd.sun.wadl+xml", 118 | "rel": "describedby" 119 | }, 120 | { 121 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 122 | "type": "application/vnd.sun.wadl+xml", 123 | "rel": "describedby" 124 | } 125 | ] 126 | } 127 | } 128 | 203: 129 | description: |- 130 | 203 response 131 | content: 132 | application/json: 133 | examples: 134 | foo: 135 | value: { 136 | "version": { 137 | "status": "CURRENT", 138 | "updated": "2011-01-21T11:33:21Z", 139 | "media-types": [ 140 | { 141 | "base": "application/xml", 142 | "type": "application/vnd.openstack.compute+xml;version=2" 143 | }, 144 | { 145 | "base": "application/json", 146 | "type": "application/vnd.openstack.compute+json;version=2" 147 | } 148 | ], 149 | "id": "v2.0", 150 | "links": [ 151 | { 152 | "href": "http://23.253.228.211:8774/v2/", 153 | "rel": "self" 154 | }, 155 | { 156 | "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", 157 | "type": "application/pdf", 158 | "rel": "describedby" 159 | }, 160 | { 161 | "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", 162 | "type": "application/vnd.sun.wadl+xml", 163 | "rel": "describedby" 164 | } 165 | ] 166 | } 167 | } 168 | --------------------------------------------------------------------------------