OpenAPI is akin to a magical translator, turning RESTful HTTP API details into machine-readable scripts. Imagine a universal language, where neither humans nor machines require Sherlock Holmes-style investigations through source codes, documentation, or network traffic to understand an API.
Welcome, curious readers! Let’s dive deep into the world of OpenAPI, a realm where APIs are no longer just a maze of codes, but beautifully structured, understandable masterpieces.
The Essence of OpenAPI
OpenAPI is akin to a magical translator, turning RESTful HTTP API details into machine-readable scripts. Imagine a language that’s universal, where neither humans nor machines require Sherlock Holmes-style investigations through source codes, documentation, or network traffic to understand an API. That’s OpenAPI for you!
And before you jump the gun, no, it’s not just another YAML or JSON document. Think of it more as the noble RFCs or those documents from the Internet Engineering Task Force (IETF) – structured, meticulous, and standardized.
A Stroll Down Memory Lane
The Humble Beginnings (2010): Once upon a time, Tony Tam, an innovator from Reverb Technologies, birthed Swagger to standardize API descriptions.
Swagger’s Glory Days (2011-2014): Like any great invention, Swagger swiftly stole the limelight as the go-to framework for API spec.
The Plot Twist (2015): Recognizing its brilliance, SmartBear Software adopted Swagger.
Evolving into OpenAPI (2015): In an act of unparalleled benevolence, SmartBear passed the Swagger Specification baton to the Linux Foundation. Thus, the OpenAPI Initiative was born, and Swagger Specification transformed into the OpenAPI Specification (OAS).
The Grand Update (2017): OAS 3.0 emerged, bringing along sophisticated features like callbacks and webhooks.
The Masterminds Behind the Specs
OpenAPI specs are not just any regular documents; they’re crafted with precision by:
- Visionary Product Owners👩🏼🏫
- Artistic Front-end Engineers👱🏼
- Tech-savvy Mobile Engineers 📱
- Genius Back-end Developers 🧑🏻
Breaking Down OpenAPI Specifications
Let’s dissect what goes into these specifications:
- Version: The keystone of OAS. It religiously follows Semantic Versioning 2.0.0.
- Info: Vital metadata about the API, a must-have in any spec.
- Servers & Paths: The bread and butter, defining where the API resides and its various endpoints.
- Components: The buffet section, offering everything from data models (schemas) to security definitions (securitySchemes).
- Webhooks, Security & Tags: More like the dessert, optional but offering immense value.
- External Documents & Vendor Extensions: The cherry on top, providing references to external documentation or adding custom vendor data.
Enrich Your Specs: Essential Editing Tools
Curating a fine OpenAPI specification is an art, and every artist needs their tools. Here’s your palette:
- Swagger Editor: Think of it as your paintbrush, helping you craft specifications with precision.
- Stoplight Studio & APICurio Studio: Your canvases, offering a platform to envision and design.
- Redocly’s OpenAPI CLI: A multitasking marvel, aiding in linting, bundling, and more.
- Postman: The magnifying glass, primarily for testing, but also a worthy editor.
- Visual Studio Code: The studio space, where the actual crafting takes place with handy extensions.
- Speca: Collaborate, design, and bring your API vision to life.
Using CreateAPI to Generate iOS Code
Create a Swift Package
Initiate Swift package
mkdir PetstoreKit cd PetstoreKit swift package init --type library
Download the desired Specs in OpenAPI format
curl "https://petstore3.swagger.io/api/v3/openapi.json" > PetStore.json
Make a CreateAPI config file create-api-config.yaml and specify the name of you main package
module: PetstoreKit #Modifier for all generated declarations
Modify the Package.swift:
Add dependencies to Get, URLQueryEncoder and HTTPHeaders
dependencies: [ package(url: "https://github.com/kean/Get", from: "2.0.0"), .package(url: "https://github.com/CreateAPI/URLQueryEncoder", from: "0.2.0"), ``.package(url: "https://github.com/CreateAPI/HTTPHeaders", .upToNextMajor(from: "0.1.1")), `` ], ... .target( name: "iolapopenapiswift", `dependencies: [ `` ``.product(name: "Get", package: "Get"),`` ``.product(name: "URLQueryEncoder", package: "URLQueryEncoder"),`` ``.product(name: "HTTPHeaders", package: "HTTPHeaders"),`` ``],`` ``path: "Sources", ``exclude: ["PetStore.json", `` `` "create-api-config.yaml"] ),
Change the package file to use create-api as a binary target
.binaryTarget(
name: "create-api",
url: "https://github.com/CreateAPI/CreateAPI/releases/download/0.2.0/create-api.artifactbundle.zip",
checksum: "6f8a3ce099f07eb2655ccaf6f66d8c9a09b74bb2307781c4adec36609ddac009"
),For further code modification is needed, write a Swift package plugin
Command plugin resides in Plugins/GenerateAPI/Plugin.swift
The method to implement
struct Plugin: CommandPlugin {func performCommand(context: PluginContext, arguments _: [String]) async throws {
// implement this To invoke the plugin (and generate code) run this from the command line:
swift package --allow-writing-to-package-directory generate-api
This command generates folder structure like this:
Sources/ ├── Entities/ ├── Address.swift ├── APIResponse.swift ├── Category.swift ├── Customer.swift ├── Order.swift ├── Pet.swift ├── Tag.swift └── User.swift ── Extensions/ ├── Paths.swift └── StringCodingKey.swift ── PetstoreKit/ └── PetstoreKit.swift ├── Paths/ ├── PathsPetAPI.swift ├── PathsPetFindByStatusAPI.swift ├── PathsPetFindByTagsAPI.swift ├── PathsPetWithPetIDAPI.swift ├── PathsPetWithPetIDUploadImageAPI.swift ├── PathsStoreAPI.swift ├── PathsStoreInventoryAPI.swift ├── PathsStoreOrderAPI.swift ├── PathsStoreOrderWithOrderIDAPI.swift ├── PathsUserAPI.swift ├── PathsUserCreateWithListAPI.swift ├── PathsUserLoginAPI.swift ├── PathsUserLogoutAPI.swift └── PathsUserWithUsernameAPI.swift ├── create-api-config.yaml └── PetStore.md
The result is a complete iOS networking client code,
- Generated from the OpenAPI specs,
- Crafted to the detail to serve our specific needs,
- Able to be updated any time, hassle-free,
- Ready to be used,
- In a distinct target, completely decoupled from the rest of the app,
- Testable in stand-alone way
- Usable in any other app that depends on the same backend specs
In summary, OpenAPI has transformed the once chaotic realm of APIs into a harmonized, structured world. Whether you’re a newbie or a pro, this guide should help you appreciate the nuances of OpenAPI and its pivotal role in modern tech.
Check out how our App Design & Development can help you with your business and get in touch.
Happy API crafting! 🚀
Let's collaborate
Partner with us
Let’s work together to create smarter, more effective solutions for your business.
Related blogs
Brand safety in programmatic is of paramount importance. A single misplaced ad can spark backlash, eat into your ROI, and damage years of brand building. And AI has only raised…
Business process automation (BPA) was once limited to rigid, rule-based workflows. Today, it’s evolving into something smarter, thanks to AI. If you’re aiming to streamline your operations and improve efficiency,…
AI is becoming an undeniable part of everyday corporate life. By taking on repetitive tasks and processing large amounts of data, it frees your workforce up to focus on making…
Who we are
Explore how our culture and expertise fuel digital innovation
Join us