A Swagger container based on Windows in Docker
Introduction
Suppose there is some server with an API that was not natively given Swagger. For simplicity we will call it
API
It may run in a Docker container based on Windows. The task is to bring up a working Swagger to demonstrate
Try it out requests from it.
You can add it to the existing container or bring up a new one alongside.
We will bring up a new one alongside, following the principle
One service - one container
Project structure
Since the container is based on Windows, this project will use Docker with
Windows engine
, so all other containers will be based on
Windows
that is, it will not be possible to use the native container swaggerapi/swagger-ui .
From the Plain old HTML/CSS/JS (Standalone) section
of the official instructions
on installing Swagger we can learn that the current version can be downloaded as an archive
here
.
This example uses version
5.11.10
we will download and configure it with a
PowerShell
script, but I also recommend downloading this directory manually and studying the contents. The main directory in which we will work is dist
separate_containers/ |-- docker-compose.yml `-- dockerfiles |-- Dockerfile.server |-- Dockerfile.swagger.python |-- setup.ps1 |-- src | `-- bin | `-- Server.exe `-- swagger_config `- dist |-- swagger-initializer.js `-- swagger.json
Dockerfile.server
and the directory src/bin
belong to the API.
We are little interested in what is inside, the main thing is that the Docker image fits our
Windows
Suppose
the Docker file
looks like this
# Dockerfile.server # Host: Microsoft Windows [Version 10.0.22621.3155] FROM mcr.microsoft.com/windows/nanoserver:ltsc2022 COPY src/bin/ /bin EXPOSE 9500 WORKDIR /bin ENTRYPOINT ["Server.exe"]
Dockerfile.swagger.python we need it to run an http server in the directory swagger-ui/dist
# Dockerfile.swagger.python # Host: Microsoft Windows [Version 10.0.22621.3155] FROM python:3.12.2-windowsservercore LABEL author="https://devhops.site" COPY swagger-ui /swagger-ui WORKDIR /swagger-ui/dist ENTRYPOINT [ "python", "-m", "http.server" ]
If for some reason the image based on Python does not suit you, you can use the servercore image and install there Node.js
# Dockerfile.swagger.node # Host: Microsoft Windows [Version 10.0.22621.3155] FROM mcr.microsoft.com/windows/servercore:ltsc2022 LABEL author="www.DevHops.site" RUN powershell.exe -Command \ Invoke-WebRequest -OutFile nodejs.zip -UseBasicParsing "https://nodejs.org/download/release/v16.20.2/node-v16.20.2-win-x64.zip"; \ Expand-Archive -Path nodejs.zip -DestinationPath C:\; \ Rename-Item "C:\node-v16.20.2-win-x64" C:\nodejs; WORKDIR "C:\nodejs" RUN setx path "%path%;C:\nodejs" WORKDIR /bin COPY swagger-ui /swagger-ui RUN npm install -g http-server WORKDIR /swagger-ui/dist ENTRYPOINT [ "http-server", "--cors" ]
docker-compose.yml
A simple compose file docker-compose.yml links the containers together.
# docker-compose.yml services: compose-swagger-win: build: context: ./dockerfiles dockerfile: Dockerfile.swagger.python ports: - "8002:8000" container_name: compose_swagger_win compose-colreg-server: build: context: ./dockerfiles dockerfile: Dockerfile.colreg ports: - "9500:9801" container_name: compose_colreg_win
A file with the API description has to be prepared. Since this was not done automatically, information will have to be scraped piece by piece, for example
from request bodies and so on.
You can install Swagger editor beforehand and write the openapi.yaml file there, and then
convert it to JSON
One way or another, you need to prepare
swagger.json
{ "openapi": "3.0.3", "info": { "title": "www.TopBicycle.ru", "version": "0.1.0" }, "servers": [ { "url": "http://localhost:9500" } ], "paths": { "/endpoint": { "post": { "summary": "Update bike Info", "operationId": "update_bike_info_bikes_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_update_bike_info_bikes_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "headers": { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "*", "Access-Control-Allow-Headers": "*" }, "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_update_bike_info_bikes_post": { "type": "array", "items": { "$ref": "#/components/schemas/bikes" }, "required": [ "bike1", "bike2" ], "title": "Body_update_bike_info_bikes_post" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Info": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "manuf": { "type": "string", "title": "Manufacturer" }, "type": "object", "required": [ "id", "name", "manuf" ], "title": "Info" } }, "Bikes": { "properties": { "bike1": { "$ref": "#/components/schemas/Bike" }, "bike2": { "$ref": "#/components/schemas/Bike" } }, "required": [ "bike1", "bike2" ] }, "Bike": { "properties": { "info": { "$ref": "#/components/schemas/Info" }, "type": "object", "required": [ "info" ], "title": "bike" } } } } }
Then let us prepare the file swagger-initializer.js
window.onload = function() { //<editor-fold desc="Changeable Configuration Block"> // the following lines will be replaced by docker/configurator, when it runs in a docker-container window.ui = SwaggerUIBundle({ url: "swagger.json", dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" }); //</editor-fold> };
If we were running a native container, we would most likely have to edit the file translator.js from swagger-ui/docker/configurator
… url: { value: "swagger.json", schema: { type: "string", base: true } }, …
But we do not need that now. These files can be downloaded beforehand here as already said at the beginning of the article.
Building and running
The project will be built and run by the script setup.ps1 which will first download and unpack the archive with swagger-ui then put the pre-prepared files there swagger.json and swagger-initializer.js and then execute the commands docker compose up --build
$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 ${pwd} "swagger_config\dist\swagger.json"; $initializer_path = Join-Path ${pwd} "swagger_config\dist\swagger-initializer.js"; # $translator_path = Join-Path ${pwd} "swagger_config\docker\configurator\translator.js"; $dist = Join-Path ${pwd} "${SWAGGER_DIR}\dist\"; # $configurator = Join-Path ${pwd} "${SWAGGER_DIR}\docker\configurator\"; 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} Copy-Item -Path ${json_path} -Destination ${dist} -Recurse -force Copy-Item -Path ${initializer_path} -Destination ${dist} -Recurse -force # Copy-Item -Path ${translator_path} -Destination ${configurator} -Recurse -force } docker compose build docker compose up
After the build finishes you will need to open in a browser, for example in Firefox the address
localhost:8002
And in the opened Swagger UI perform Try it out requests to the API
Article author: Andrei Olegovich