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! 🚀