Schema

The schema is structured in to 5 sections:

Meta

Meta-data which describes the API.

swagger: "2.0" info: description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters." version: "1.0.0" title: "Swagger Petstore" termsOfService: "http://swagger.io/terms/" contact: email: "apiteam@swagger.io" license: name: "Apache 2.0" url: "http://www.apache.org/licenses/LICENSE-2.0.html" host: "petstore.swagger.io" basePath: "/v2" schemes: - "https" - "http"

Tags

tags define groupings of API models and paths and are assigned by the tag property within a model (accepting an array of tags)

tags: - name: "pet" description: "Everything about your Pets" externalDocs: description: "Find out more" url: "http://swagger.io" - name: "store" description: "Access to Petstore orders" - name: "user" description: "Operations about user" externalDocs: description: "Find out more about our store" url: "http://swagger.io"

API Methods

paths: /path/to/api/method/{query_params}/complete: // {variable placeholder} get: // Request Verb (get|post|put|delete|patch) tags: - "pet" summary: "Update an existing pet" description: "" operationId: "updatePet" // Implementation method name consumes: - "application/json" - "application/xml" produces: - "application/xml" - "application/json" parameters: - in: "body" name: "body" description: "Pet object that needs to be added to the store" required: true schema: $ref: "#/definitions/Pet" // References yaml model. responses: 400: description: "Invalid ID supplied" 404: description: "Pet not found" 405: description: "Validation exception" security: - petstore_auth: // Defined in block securityDefinitions - "write:pets" - "read:pets"

Models

definitions: Pet: type: "object" required: - "name" - "photoUrls" properties: id: type: "integer" format: "int64" category: $ref: "#/definitions/Category" // Reference to other model definitions. name: type: "string" example: "doggie" photoUrls: type: "array" xml: name: "photoUrl" wrapped: true items: type: "string" tags: type: "array" xml: name: "tag" wrapped: true items: $ref: "#/definitions/Tag" status: type: "string" description: "pet status in the store" enum: - "available" - "pending" - "sold" xml: name: "Pet"

Security

securityDefinitions: petstore_auth: type: "oauth2" authorizationUrl: "http://petstore.swagger.io/oauth/dialog" flow: "implicit" scopes: write:pets: "modify pets in your account" read:pets: "read your pets" api_key: type: "apiKey" name: "api_key" in: "header"

Code Generation

Gradle Configuration

buildscript { repositories { mavenLocal() mavenCentral() } dependencies { classpath "org.openapitools:openapi-generator-gradle-plugin:3.3.4" } } apply plugin: 'org.openapi.generator' openApiGenerate { generatorName = "kotlin" // java inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() outputDir = "$buildDir/generated".toString() apiPackage = "org.openapi.example.api" invokerPackage = "org.openapi.example.invoker" modelPackage = "org.openapi.example.model" modelFilesConstrainedTo = [ "Error" ] configOptions = [ dateLibrary: "java8" ] }

References