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.
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.
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.
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 π§π»
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.
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.
Initiate Swift package
mkdir PetstoreKit
cd PetstoreKit
swift package init --type library
curl "https://petstore3.swagger.io/api/v3/openapi.json" > PetStore.json
module: PetstoreKit
#Modifier for all generated declarations
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"]
),
.binaryTarget(
name: "create-api",
url: "https://github.com/CreateAPI/CreateAPI/releases/download/0.2.0/create-api.artifactbundle.zip",
checksum: "6f8a3ce099f07eb2655ccaf6f66d8c9a09b74bb2307781c4adec36609ddac009"
),
The method to implement
struct Plugin: CommandPlugin {
func performCommand(context: PluginContext, arguments _: [String]) async throws {
// implement this
}
swift package --allow-writing-to-package-directory generate-api
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! π