OpenApi

Введение

The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.

Previously part of the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation.

An OpenAPI document represents a formal description of an API that tools can use to generate code, documentation, test cases, and more.

Подготовка окружения

From Plain old HTML/CSS/JS (Standalone) secton of Swagger official manual we can learn that latest version can be downloaded from here as an archive .

In this article we will use version 5.11.10

PowerShell script is provided for fast download and unpacking - here

Subdirectory of our interest is dist

Step by step setup instructions can be found here

Структура проекта

If you have not followed step by step guide yet this is how we get this setup:

Create an empty dir e.g. sandbox and download→unzip swagger-ui archive to this dir or use setup.ps1 script that will do it automatically.

sandbox/ |-- setup.ps1 `-- swagger-ui |-- Dockerfile |-- LICENSE |-- NOTICE |-- README.md |-- SECURITY.md |-- babel.config.js |-- composer.json |-- config |-- cypress.config.js |-- dev-helpers |-- dist | |-- favicon-16x16.png | |-- favicon-32x32.png | |-- index.css | |-- index.html | |-- oauth2-redirect.html | |-- swagger.json | |-- swagger-initializer.js | |-- swagger-ui-bundle.js | |-- swagger-ui-bundle.js.map | |-- swagger-ui-es-bundle-core.js | |-- swagger-ui-es-bundle-core.js.map | |-- swagger-ui-es-bundle.js | |-- swagger-ui-es-bundle.js.map | |-- swagger-ui-standalone-preset.js | |-- swagger-ui-standalone-preset.js.map | |-- swagger-ui.css | |-- swagger-ui.css.map | |-- swagger-ui.js | `-- swagger-ui.js.map |-- docker |-- docs |-- flavors |-- package-lock.json |-- package.json |-- patches |-- release |-- renovate.json |-- snapcraft.yaml |-- src |-- swagger-config.yaml |-- swagger-ui-dist-package |-- test `-- webpack

PowerShell скрипт

Скачать setup.ps1

# setup.ps1 $SWAGGER_VERSION = "5.11.10" $SWAGGER_URL = "https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_VERSION}.zip"; $SWAGGER_DIR = "swagger-ui" $swagger_ui_path = Join-Path ${pwd} ${SWAGGER_DIR}; $json_path = Join-Path ${SWAGGER_DIR} "dist\swagger.json"; If (Test-Path -path ${swagger_ui_path}) { Write-Host "${SWAGGER_DIR} dir exists" -f Green; } Else { Write-Host "${SWAGGER_DIR} dir does not exist - starting download" -f Yellow Invoke-WebRequest $SWAGGER_URL -OutFile swagger-ui.zip Expand-Archive -Path swagger-ui.zip -DestinationPath . Remove-Item swagger-ui.zip Rename-Item -Path "swagger-ui-${SWAGGER_VERSION}" -NewName ${SWAGGER_DIR} } New-Item -Path $json_path -Force -ItemType "file"

All characters appearing in this article are fictitious. Any resemblance to real persons is purely coincidental

swagger.json

Copy the following code to your swagger.json ( Download )

This file contains code for minimalistic API specification plus one GET endpoint description that is supposed to return a list of test engineers that were present on a certain meeting.

{ "openapi": "3.1.0", "info": { "title": "QA Demo REST API", "version": "0.0.1" }, "servers": [ { "url": "http://justapi.ru" } ], "paths": { "/testers": { "get": { "summary": "Get List of Test Engineers", "operationId": "Get_List_of_Test_Engineers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "title": "Testers" } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "basicAuth": [] } ] }

swagger-initializer.js

Edit the swagger-initializer.js file's url parameter. It shoud be pointing to our swagger.json file

… url: "swagger.json", …

HTTP server

Install Python and inside dist directory run

python -m http.server

If server has started successfully you should see similar output

Serving HTTP on :: port 8000 (http://[::]:8000/) ... ::ffff:127.0.0.1 - - [11/Apr/2024 13:50:54] "GET /swagger.json HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET / HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-initializer.js HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /index.css HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui.css HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui-standalone-preset.js HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui-bundle.js HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger.json HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /favicon-32x32.png HTTP/1.1" 200 -

In case if you are restarting the server you will most likely get 304 HTTP respose instead of 200

Serving HTTP on :: port 8000 (http://[::]:8000/) ... ::ffff:127.0.0.1 - - [16/Apr/2024 14:22:28] "GET / HTTP/1.1" 304 - ::ffff:127.0.0.1 - - [16/Apr/2024 14:22:32] "GET / HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET / HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui.css HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET /index.css HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui-bundle.js HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-ui-standalone-preset.js HTTP/1.1" 304 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger-initializer.js HTTP/1.1" 200 - ::1 - - [13/Dec/2024 00:13:03] "GET /swagger.json HTTP/1.1" 200 -

Client UI

Now everything is ready for you to access REST client UI

In browser e.g. in Firefox or even better in Edge open

localhost:8000

Expand the endpoint by clicking the ∨ symbol on the right (near the 🔒 lock symbol)

After endpoint info is expanded click Try it out button

Click Execute button

Check Server response block: Code should be 200 and Response body should contain the list of strings.

Step by step

0

Install Python with this man or any other way you prefer.

We will use Python mainly to run HTTP server. I also use it to convert my .yaml files to .json and vice versa.

Alternatively install any other tool that can provide you with simple HTTP server, e.g. NodeJS you name it.

1

Create an empty dir e.g. sandbox.

It can be located at

C:\Users\Username\sandbox

2

Download this swagger-ui archive from here and put it to sandbox dir

3

Unzip archive and rename dir from swagger-ui-5.11.10 to swagger-ui. Delete .zip file

4

Go to swagger-ui/dist directory.

5

Create empty swagger.json file there.

6

Copy content from this example to your swagger.json and save it.

7

Edit url in swagger-initializer.js file like this: url: "swagger.json" (example)

8

Go to dist subdirectory of swagger-ui dir and start http server by executing

python -m http.server

Make sure that you are executing python -m http.server command inside dist directory

9

Open your browser and enter localhost:8000 to address bar.