OpenAPI - What is it?

The OpenAPI Specification is a specification language for HTTP APIs that provides a standardized means to define your API to others. You can quickly discover how an API works, configure infrastructure, generate client code, and create test cases for your APIs. Read more about how you can get control of your APIs now, understand the full API lifecycle and communicate with developer communities inside and outside your organization. (Source)

Evolution of a specification

				title: Root Type for Toy
				description: |-
					Something big and small like to play with.
					Inanimate, but eventual animatronic.
					Definitely not a pet or a human
				type: object
				properties:
					Name:
						type: string
					Color:
						type: string
					Shape:
						type: string
				example:
					Name: Matchbox
					Color: red
					Shape: Zylinder
				

missed the {}?

				{
					"title": "Root Type for Toy",
					"description": "Something big and small like to play with.\nInanimate, but eventual animatronic.\nDefinitely not a pet or a human",
					"type": "object",
					"properties": {
						"Name": {
							"type": "string"
						},
						"Color": {
							"type": "string"
						},
						"Shape": {
							"type": "string"
						}
					},
					"example": {
						"Name": "Matchbox",
						"Color": "red",
						"Shape": "Zylinder"
					}
				}
				

Strict on input

				title: Root Type for Toy
				description: |-
					Something big and small like to play with.
					Inanimate, but eventual animatronic.
					Definitely not a pet or a human
				type: object
				properties:
					Name:
						type: string
					Color:
						type: string
					Shape:
						type: string
				additionalProperties: false
				example:
					Name: Matchbox
					Color: red
					Shape: Zylinder
				

Mandating fields

				required:
					- Name
					- Color
				type: object
				properties:
					Name:
						description: How will your kid call it?
						minLength: 3
						type: string
					Color:
						type: string
					Shape:
						type: string
				additionalProperties: false
				

selecting choices

				required:
					- Name
					- Color
				type: object
				properties:
					Name:
						description: How will your kid call it?
						minLength: 3
						type: string
					Color:
						enum:
							- red
							- green
							- yellow
						type: string
					Shape:
						type: string
				additionalProperties: false
				

Demo

Many more

Missing

• custom functions
• cross item constrains

Where to use

and where not

Separation of control

Q & A