Draft

Generating SDKs from OpenAPI

A repeatable way to generate SDKs from OpenAPI specs using Docker
playbook
python
openapi
client-sdk
Author

Peter Ramsing

Published

April 13, 2025

I tried this one:

Choosing OpenAPI Tools - OpenAPI Generator

I went with the one that worked when I could skip the validation for the OpenAPI spec that our client had provided. - https://github.com/OpenAPITools/openapi-generator

Start with repeatable

As with nearly everything, I want to have a repeatable way to create what we’re working on regardless of what platform we’re on. …and be able to share things across systems. So in that vein I want to use Docker to create a repeatable environment for generating SDKs from OpenAPI specs.

I built out some code that combines all this with a Makefile: https://github.com/FocusedDiversity/synaptiq-sdk-generator.git

Getting your Swagger spec

What you’re looking for is an OpenAPI spec. This is a JSON or YAML file that describes your API. You can get this from your API provider or generate it yourself if you have access to the API code.

NOAA Example

https://www.weather.gov/documentation/services-web-api

Direct download: https://api.weather.gov/openapi.json

Setup the Swagger Editor

docker-compose.yml:

services:
  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: swagger-editor
    platform: linux/amd64
    ports:
      - "8081:8080"
    volumes:
      - ./api:/tmp
    environment:
      - SWAGGER_FILE=/tmp/${SCHEMA_FILE_NAME}

Note the folder mapping. This assumes the following folder structure:

|docker-compose.yml
|-- api/
|---- <SCHEMA_FILE_NAME> (your OpenAPI spec)
|-- sdk-output/

Generate the SDK

(adjust as needed for your platform) Also note that I added the --skip-validate-spec flag. Use this at your own risk but I’m feeling a bit dangerous today.

rm -rf "${PWD}/sdk-output/python-sdk"
docker run --rm --platform linux/amd64 -v "${PWD}/api:/local/api" -v "${PWD}/sdk-output:/local/out" openapitools/openapi-generator-cli generate $(if $(SKIP_VALIDATE),--skip-validate-spec) \
    -i /local/api/$(FILE_NAME) \
    -g python \
    -o /local/out/python-sdk \
    --additional-properties=packageVersion=$(VERSION)
docker run --rm --platform linux/amd64 -v "${PWD}/sdk-output/python-sdk:/local" -w /local python:3.9 bash -c "python setup.py sdist"

If you need to adjust the version of the client SDK (not to be confused with the schema version) that can be done with this flag:

--additional-properties=packageVersion=1.1.0

This will generate the SDK in the sdk-output/python-sdk folder.

Using the SDK in Databricks

Now you can upload this to your Databricks workspace and install it as a library.

%pip install ./openapi_client-1.1.0.tar.gz
dbutils.library.restartPython()

You can now use the API client in your Databricks notebooks.

from openapi_client import Client