Openapi 3.0 specification

Objective

Write an openapi 3.0 specification for Flask RESTful application.

Getting started

Flask RESTful application

The Flask RESTful application deals with course management system where students can execute CRUD operation to manage their courses. To successfully build the Flask RESTful application, please follow the blog, titled "FLASK AND MONGO" under RESTFUL API. The code can be downloaded from the following link. To check out the schemas and the path definitions, please click the links.

Openapi 3.0 specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. For more details, follow the link.

To write the openapi specification, you can use Swagger Editor or Visual Studio Code and Swagger UI. This article prefers to write the specification using VS Code and Swagger UI. The docker image of Swagger UI is downloaded from dockerhub.

File structure


flaskREST
|- app.py
|__swagger
	|- openapi.yaml
|__database
	|- db.py
	|- models.py

Openapi definition

The basic structure of openapi specification 3.0.0 :


openapi: 3.0.0 REQUIRED

info: REQUIRED
	title: REQUIRED
	version: REQUIRED
	description:
	termsOfService:
	contact:
	license:
	version:

servers:
	- url: REQUIRED
		description:
		variables:

paths: REQUIRED
	/<endpoint>:
		get/post/put/delete/..:
		tags:
		summary:
		description:
		operationId:
		externalDocs:
			description:
			url: REQUIRED
		parameters:
			name: REQUIRED
			in: REQUIRED
			required: REQUIRED
			description:
			deprecated:
			allowEmptyValue:
			.
			.
		responses: REQUIRED
			<HTTP Status Code>:
				description: REQUIRED
				headers:
				content:
					<content-type>:
						schema:
						example:
						examples:
						encoding:
				links:
		deprecated:
		security:
		servers:
		requestBody:
			description:
			contact: REQUIRED
				<content-type>:
					schema:
					example:
					examples:
					encoding:
			required:
		callbacks:

# To reference a definition, "$ref" keyword is used and the definitions are under the compnents tag
components:
	schemas:
	responses:
	parameters:
	examples:
	requestBody:
	headers:
	securitySchemes:
	links:
	callbacks:

To get familiar with each and every items of Openapi Specification, please visit the following web link.

To start both services


Flask Application:
FLASK_APP=app.py FLASK_ENV=developement flask run

Terminal output:
* Serving Flask app "app.py" (lazy loading)
* Environment: development
* Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger PIN: 188-695-452

Swagger UI:
docker run --name swaggerUI --rm -p 8080:8080 -e SWAGGER_JSON=/foo/openapi.yaml -v $PWD/swagger:/foo swaggerapi/swagger-ui

The application server is running on http://localhost:5000 and the Swagger UI is running on http://localhost:8080. An example of browser output looks like this:

Download code: Github