We just posted a course on the freeCodeCamp.org YouTube channel that will teach you to build a feature-rich movie and TV browsing app with a dynamic home screen, powerful search, and detail screens that play YouTube trailers.

You will also implement a download manager to save titles for offline viewing using SwiftData. By integrating The Movie Database and YouTube APIs, this project provides excellent hands-on practice with SwiftUI, API integration, and modern data storage. Carlos Valentin created this course.

Here are the sections in this course:

• Essentials

• Networking

• API Networking Requests

• Navigation

• Search

• SwiftData

Watch the full course on the freeCodeCamp.org YouTube channel (4-hour watch).

For many app developers, including me, writing the networking layer of an application is a familiar and tedious process. You write and test your first call and after that, it involves a repetitive cycle of tasks.

This is how it would look in the case of Swift:

1. You create a URLSession Instance.

2. You create a URLRequest Object.

3. You create the @Codable models to match the expected input and output from the server.

You do the above steps for each API endpoint you have on your backend that your app uses. Not only is this process time-consuming and not challenging for developers, it’s also error prone.

In the above case, if there was a minor change in the backend API – perhaps a renamed field or a new property – this would lead to the app potentially breaking. But you wouldn’t know this until you shipped it to QA or in a worse case, your consumer. This is where the OpenAPI Specification emerges as a modern, robust solution.

In this tutorial, you’ll learn what OpenAPI is and how it can help make your development process better. After that, we’ll implement OpenAPI by creating a small SwiftUI app and using OpenAPI methodologies to interface with the JSONPlaceholder API. Let’s get started.

Who is This Guide For?

This guide is intended both for new developers looking for best practices and for experienced developers looking to implement or learn more about the OpenAPI Specification. Let’s get into it.

Table of Contents

• What is OpenAPI and Why Should You Care?

  • Benefits for Swift (iOS) Developers

• A Practical Guide to Implementing This Solution

  • Step 1: Create a good openapi.yaml file (the specification)

  • Step 2: Set up your project

  • Step 3: Write a wrapper

  • Step 4: Call the wrapper and display the data

• Potential Pitfalls

  • Verbose or ugly generated code

  • Large Specs and Performance Issues

  • Unsupported Spec Features

• Conclusion: Embrace Spec-Driven Development

What is OpenAPI and Why Should You Care?

At its core, the OpenAPI Specification provides a standard, language-agnostic interface for describing RESTful APIs. This specification, once populated, allows both humans and computers to discover and understand the capabilities of a service without needing to access the source code or the network requests.

The power of OpenAPI is that it acts as a formal contract between different parts of the system. This contract helps both frontend and backend programmers by removing ambiguity during design process. This also has added benefit of using code generators to generate boiler-plate code both on backend and on the client ( which we will also discuss today ).

Traditionally when you want to create a new API in a team, either the PM, the frontend engineer, or the backend engineer takes it upon themselves to request it. Then the backend team builds it and documents it. This in turn is used by the front end team to use the API.

Some Requester → Backend Team → Documentation → Frontend Team

If you’re using OpenAPI, when someone makes a request for a new API, it is formalized into a specification after deliberations with both the frontend and the backend team. This then serves as the source of truth and is used to generate the backend and the frontend code without as much interdependence.

Some Requester → All Teams → Specification → All Teams.

This not only streamlines the process of adding new APIs, but provides a definitive source of truth for each endpoint. This also makes it so that frontend engineers and backend engineers are not misaligned about a provided parameter in the result being an Int or a String and so on. It’s all in the Spec.

Benefits for Swift (iOS) Developers

Adopting OpenAPI and swift-openapi-generator brings a host of tangible benefits to the Swift/App development process. It transforms how applications interact with web services in a few key ways.

Reduced Development Time and Cost

The most immediate improvement you will see is the significant reduction in boilerplate code you have to write. The generator automates the creation of what is called boilerplate code or ceremonial code. This is the repetitive logic for network requests, response handling, and data model definitions.

By delegating this work, developers can work on the core features of the application which leads to faster and more interesting development cycles.

Compile Time Type Safety

This has been a major improvement for me personally. Instead of relying on the “strongly” typed keys for JSON parsing, we now work with strongly typed models. The generator creates native Swift struct and enum types directly from the schemas defined in the OpenAPI document. This brings the power of a strongly-typed system to the networking and parsing layer.

For example, if the return value of an API is made optional, instead of crashing at runtime, we will fail to compile at build time. This forces us to address this issue right away.

Improved Collaboration and Interoperability

This makes sure that all the developers are on the same page with regard to a given endpoint. And since this specification is language agnostic, it will serve as a universal language for all teams involved in the project – mobile, web and backend.

Other Tooling

Once you have a specification, you can use that to power a wide variety of tools. You can generate interactive documentation, create mock servers for frontend development, and run automated tests.

Alright hopefully you’re sold – so now how do you implement this into your project?

A Practical Guide to Implementing This Solution

We’ll now take a look at a practical example so you can understand how you can implement this in a project. This involves:

• Creating an openapi.yaml file to describe the API specification.

• Configuring and integrating swift-openapi-generator into a SwiftUI application.

• Prototyping an app that fetches and displays a list of posts from the https://jsonplaceholder.typicode.com/

To follow along, you will need Xcode installed and a basic understanding of Swift programming and SwiftUI for App development.

Step 1: Create a good openapi.yaml file (the specification)

The quality of a specification is really important because it directly determines the quality of the code produced by swift-openapi-generator. If you don’t have a good specification, you might run into several issues that developers often complain about, like confusing and long method names.

For example, it might generate something like get_all_my_meal_recipes_hyphen_detailed. This might happen because the generator is forced to create a new name based on the API path if the identifier is not provided in the spec. So, instead of dealing with these issues one after the other, we will create a good clear specification to start with.

Since we’re using the jsonplaceholder as our backend server, we are limited by what tweaks we can make – but it is a fantastic project that lets us mimic a backend server.

In general, an OpenAPI.yaml file contains:

1. OpenAPI Info and servers – This will provide the metadata about the API like the OpenAPI version, which server to point to for calls, and so on.

2. Paths – This will provide the available endpoints. In our case, it can contain /posts as one of them. We also will have to mention the kind of endpoint (get, post, put, and so on)

3. OperationID – This field instructs the generator to create a clear method with this name.

4. Responses – This defines the possible outcomes of an API call. We will specify the structure of a successful 200 OK response or any other errors here.

5. Components / Schemas – This defines all the reusable components and data models. If we have a Post schema definer here, the generator will use this to create a Post struct in Swift to match this.

Keeping in mind all these elements, I compiled a yaml file for us to use for this tutorial:

# openapi.yaml
openapi: "3.0.3"
info:
  title: "JSONPlaceholder API"
  version: "1.0.0"
servers:
  - url: "https://jsonplaceholder.typicode.com"
paths:
  /posts:
    get:
      summary: "Get all posts"
      operationId: "getPosts"
      responses:
        "200":
          description: "A list of posts"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Post"
components:
  schemas:
    Post:
      type: object
      required:
        - userId
        - id
        - title
        - body
      properties:
        userId:
          type: integer
        id:
          type: integer
        title:
          type: string
        body:
          type: string

The first line here, openapi: “3.0.3”, just tells the generators and parsers that we are using version 3.0.3.

Next, we have some more metadata – the name and version of the API. We also have the server we are calling with our APIs.

After defining this metadata, we now define our endpoints. For the sake of this example, let’s assume that we only have one endpoint to call to get posts. We represent this by saying /posts under paths. We then specify which kind it is by specifying get:.

We give a short description of what it does in the summary and then specify an operationId which is what we this function will be called in our generated code. We also specify exactly what structure the response will have, that is, a JSON of an array of Posts.

We then list any components we have across our APIs like the Post. Note that we are using the Post schema in the return response structure before we define it further down. The schemas in components will determine the Model structs we will generate using this yaml file.

Step 2: Set up your project

Create a new SwiftUI project. For the purpose of this tutorial, we’ll use an iOS app – but you can do this with any app. Select Swift as the language and SwiftUI for the interface.

Add the openapi.yaml file we just created to this project. (You can also create this file in Xcode and copy, paste from the script above.)

Now, add the following swift packages to the project. (Note: Please read the entire section about adding packages before you proceed.)

1. Swift OpenAPI Generator – https://github.com/apple/swift-openapi-generator – The Core Generator Plugin.

   

   

2. Swift OpenAPI Runtime – https://github.com/apple/swift-openapi-runtime – This contains the common types and protocols used by the code generated by the generator plugin.

   

3. Swift OpenAPI URLSession – https://github.com/apple/swift-openapi-urlsession – This is a transport layer that allows the generated code to use the Apple URLSession to make network requests.

   

One major caveat to note here when adding these packages is that The Swift OpenAPI Generator should not be added to your project target. This is because we’re only using this to generate the code, but we’re not using it in the app.

If you get this error: swift-openapi-generator/Sources/_OpenAPIGeneratorCore/PlatformChecks.swift:21:5 _OpenAPIGeneratorCore is only to be used by swift-openapi-generator itself—your target should not link this library or the command line tool directly. – then you made this mistake.

The easiest way to fix this is removing the package and adding it again. Or you can go to Project → Target → Build Phases → Link Binary with Libraries → Remove Swift OpenAPI Generator.

Now that we added these generator and runtime plugins, we need to give the generator some instructions on what to generate. You can do this with an openapi-generator-config.yaml file. For our project, use the following file. It’s really simple:

generate:
  - types
  - client

This tells our generator to generate the types – the swift structs, enums, and so on from the schema section of the file, and the client – the main class which interacts with the networking logic.

Save this into an openapi-generator-config.yaml file as shown.

And finally, we want the generator to run whenever we want to build this application/target. We can specify this in the Build Phases tab of the target. Under the “ Target → Build Phases → Run Build Tool Plug-ins” , add the OpenAPIGenerator Plugin.

The first time the project is built after setting this, Xcode will display a security dialog. This will let us “Trust and Enable” for this plugin. It’s a one time confirmation that gives this plugin the permission required to run during the build process.

As soon as you build the second time after giving these permissions, you will generate the files. You might not see any changes in the Xcode window itself. But if you’re curious to see the result, go to this folder.

DerivedData → <ProjectName>*identifier → Build → intermediates.noindex → BuildToolPluginIntermediates → <TargetName>.output → <TargetName> → OpenAPIGenerator → GeneratedSources

More on derived data folder here: https://gayeugur.medium.com/derived-data-2e9468c6da9b if you’re curious.

Keep in mind that this location might vary based on Xcode version, OpenAPI version, and your project settings. But you don’t need to worry about the file location.

You will see three files called Client.swift, Types.swift, and Server.swift.

These are the files that the our generator created and populated with the types and functions we need.

In the next section, we discuss how to use these files to make calls to the server.

Step 3: Write a wrapper

While it’s certainly possible to make the calls to server using just the generated code (Client) type throughout our application, a more maintainable approach is to use a wrapper around these types. This will provide a stable, clean interface for the rest our our app to use, and it decouples feature code from the generated code.

I can hear you thinking: “Wait a second. Isn’t the entire purpose of generating this code to avoid this boilerplate abstraction?”

While it adds some abstraction on top of the generated code, it’s valuable to have this for number of reasons. Here are but a few of them:

1. Better naming. The generated Post struct right now will be called Components.Schemas.Post.

2. If you ever want to move away from the generator, an abstraction is really helpful.

3. If you want to Mock this server call, you can do this via the abstraction.

4. UI Optimization. You might want to flatten the structure of a model to reduce the number of computed variables in there, and so on.

So, we want to wrap this around a file called WebService.swift:

// WebService.swift
import Foundation
import OpenAPIURLSession

// A clean, app-specific Post model.
// This decouples views from the generated types.
struct AppPost: Identifiable, Codable {
    let id: Int
    let title: String
    let body: String
}

class WebService {
    private let client: Client

    init() {
        // The server URL and transport are from the generated code.
        // `Servers.Server1.url()` corresponds to the first URL in the `servers` array of the spec.
        self.client = Client(
            serverURL: try! Servers.Server1.url(),
            transport: URLSessionTransport()
        )
    }

    func getPosts() async throws -> [AppPost] {
        // Call the generated method, which was named using `operationId`.
        let response = try await client.getPosts(.init())

        // The generated response is a type-safe enum covering all documented status codes.
        switch response {
        case.ok(let okResponse):
            // The body is also a type-safe enum for different content types.
            switch okResponse.body {
            case.json(let posts):
                // Map the generated `Components.Schemas.Post` to our clean `AppPost` model.
                return posts.map { post in
                    AppPost(id: post.id, title: post.title, body: post.body)
                }
            }
        // The generator forces the handling of other documented responses.
        // Our simple spec only has a 200, so any other response is undocumented.
        case.undocumented(statusCode: let statusCode, _):
            throw URLError(.badServerResponse, userInfo: ["statusCode": statusCode])
        }
    }
}

Let’s go through this file to understand what we’re doing.

First, we import OpenAPIUrlSession along with Foundation. This allows us to call the server, get a response and parse that response.

Next, we define the new AppPost struct. This is meant to be the representation of a Post in the App. In the generated Types.Swift file, we have the generated Post structure. This is defined as:

/// - Remark: Generated from `#/components/schemas/Post`.
        internal struct Post: Codable, Hashable, Sendable {
            /// - Remark: Generated from `#/components/schemas/Post/userId`.
            internal var userId: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/id`.
            internal var id: Swift.Int
            /// - Remark: Generated from `#/components/schemas/Post/title`.
            internal var title: Swift.String
            /// - Remark: Generated from `#/components/schemas/Post/body`.
            internal var body: Swift.String
            /// Creates a new `Post`.
            ///
            /// - Parameters:
            ///   - userId:
            ///   - id:
            ///   - title:
            ///   - body:
            internal init(
                userId: Swift.Int,
                id: Swift.Int,
                title: Swift.String,
                body: Swift.String
            ) {
                self.userId = userId
                self.id = id
                self.title = title
                self.body = body
            }
            internal enum CodingKeys: String, CodingKey {
                case userId
                case id
                case title
                case body
            }
        }

As you can see, our AppPost struct is different from this generated type. We omit the userId since we do not care about it (at least for now).

Back to the WebService class, we see a client attribute. This is a generated type variable that will let us interact with the servers. In the initializer of the WebService class, we create a new Client using the first server URL we specified in the schema and use the URLSessionTransport object for making these calls.

We then define our methods. In this case, our getPosts() function which returns [AppPost] array.

let response = try await client.getPosts(.init()) will call the function getPosts() on the Client object. The Client.getPosts() function here takes in an input struct called Operations.getPosts.Input which is initialized by the .init() passed here.

This generated response is a type-safe enum covering all documented codes. (Currently only 200 in our yaml file). So, we use a simple switch to look at both these cases and further use more switch statements to get the proper response. You can see how much easier this is than to parse the response manually.

Once we get the Components.Schemas.Post response, we map and convert it into [AppPost] array and return it.

Now, let’s use this wrapper to display data in our app.

Step 4: Call the wrapper and display the data

We’re at the final step now. We’ll use the wrapper we created to display the fetched posts. We’ll also use a state variable to store our AppPost array in our ContentView view. We’ll then call getPosts() when the view is first displayed to the user.

// ContentView.swift
import SwiftUI

struct ContentView: View {
    @State private var posts: [AppPost] = []
    @State private var errorMessage: String?

    private let webService = WebService()

    var body: some View {
        NavigationStack {
            List(posts) { post in
                VStack(alignment:.leading, spacing: 8) {
                    Text(post.title)
                       .font(.headline)
                    Text(post.body)
                       .font(.subheadline)
                       .foregroundColor(.secondary)
                }
               .padding(.vertical, 4)
            }
           .navigationTitle("Posts")
           .task {
                await loadPosts()
            }
           .overlay {
                if let errorMessage {
                    ContentUnavailableView("Error", systemImage: "xmark.octagon", description: Text(errorMessage))
                } else if posts.isEmpty {
                    ProgressView()
                }
            }
        }
    }

    func loadPosts() async {
        self.errorMessage = nil
        do {
            self.posts = try await webService.getPosts()
        } catch {
            self.errorMessage = error.localizedDescription
        }
    }
}

#Preview {
    ContentView()
}

You can see the dummy posts in the Preview. As you can see, all we had to do was call the webService.getPosts() to populate the variable.

You might be thinking that this is a lot of setup for a simple struct like Post for which we had to create a wrapper called AppPost anyway. But if you had ten types like this and twenty endpoints to call? You wouldn’t have to deal with a lot of repetitive, error-prone code.

Potential Pitfalls

Unfortunately, no process is perfect. You might still face a lot of issues with generated code and this method. I’ve listed some of them here and how to deal with them.

Verbose or ugly generated code

If you have very verbose or ugly generated code, the problem is almost always the missing operationId for an API path. If you don’t specify one, the generator must create a name from the path and the HTTP method with results in long unwieldy names. Adding a clear operationId will mitigate this issue.

Large Specs and Performance Issues

If you have a very large Spec file, generating a client for this entire specification can significantly increase the compile time. It can also result in absolutely massive Types.swift and Client.swift files.

There is a filter option in the openapi-generator-config.yaml file that will allow the generator to include only parts of the spec that are relevant to the application to improve build times and so on. But if you want everything in an API that has hundreds of endpoints, the only way to reduce compile times is to avoid regenerating this every time and decouple this step from the regular build process.

Unsupported Spec Features

While the swift package, swift-openapi-generator, is robust, it does not support all the features included in the specification. I had issues with some features of the newer spec version ( 3.1.1 and had to downgrade to 3.0.3 to make it work well ).

There are also known issues like lack of support for certain types of recursive schemas. Sometimes, the generator errors out and fails and some other times, it generates incomplete types – which can result in a few hours of debugging (I speak from experience).

In any case, knowing the limits of this generator can be helpful in avoiding issues it might cause. Also keep in mind that it is always getting better thanks to its open source nature.

Conclusion: Embrace Spec-Driven Development

In this guide, you navigated the journey of adopting swift-openapi-generator – from understanding the power of API contracts to building a functional SwiftUI app. You also learned about the real life challenges of this process. While there is an initial learning curve, the benefits of this approach are profound.

The core tenet of this approach is to foster more disciplined and more robust method for building applications. By making the OpenAPI document the single source of truth, you make sure that both the frontend and backend are perfectly in sync in perpetuity.

Using this approach also results in more type-safe, maintainable code. The result is less time spent on writing boilerplate and debugging random integration errors and more time spent creating the app itself.

For developers ready to explore further, please checkout the official swift-openapi-generator repository on Github here: https://github.com/apple/swift-openapi-generator.

You can follow me on GitHub and Hashnode for my other posts and projects.

This article highlights nine common accessibility challenges in mobile apps and demonstrates how SwiftUI features can help developers address these issues effectively.

Each challenge is paired with a SwiftUI solution, sample code, and testing tips to guide developers in creating accessible and user-friendly apps.

Table of Contents

• Mobile Apps Accessibility Issues and SwiftUI Solutions

  • Missing Labels and Descriptions

  • Insufficient Color Contrast

  • Small Touch Targets

  • Inaccessible Navigation

  • Lack of Feedback for Actions

  • Complex or Confusing User Interfaces

  • Lack of Support for Assistive Technologies

  • Poorly Implemented Accessibility Features

  • Insufficient Customization Options

  • References

Mobile Apps Accessibility Issues and SwiftUI Solutions

Missing Labels and Descriptions

• Challenge: Many apps lack appropriate labels or descriptions for buttons, images, and other interactive elements, making it difficult for screen readers to communicate their purpose to visually impaired users. Without these labels, users might struggle to understand the app’s functionality.

• SwiftUI Solution: SwiftUI’s .accessibilityLabel(_:) modifier allows developers to assign clear, descriptive labels to interactive elements. These labels improve navigation and understanding by giving screen readers the necessary context.

• Example:

    Label("Shop", systemImage: "cart")
        .accessibilityLabel("Go to Shop")
  

• Testing: Enable VoiceOver on an iOS device, navigate through the app, and ensure each element has an accurate label. VoiceOver should read labels clearly to help users understand each element’s purpose without needing additional explanation.

Insufficient Color Contrast

• Challenge: Low contrast between text and background colors can make it difficult for users with visual impairments to read the content, especially for those with color vision deficiencies or low vision.

• SwiftUI Solution: Use SwiftUI’s dynamic system colors (.primary and .secondary), which automatically adapt to the light or dark mode setting on the device, ensuring good readability.

• Example:

    Text("Shop")
        .foregroundColor(.primary)  // Adapts to light or dark mode automatically
  

• If custom colors are necessary, test them against WCAG standards for color contrast, using tools like Color Contrast Analyzer.

• Testing: Use Xcode’s Accessibility Inspector to verify contrast, and ensure that text remains readable in both light and dark modes. WCAG guidelines recommend a minimum contrast ratio of 4.5:1 for normal text.

Small Touch Targets

• Challenge: Small buttons or other touch areas can be difficult for users with motor impairments to interact with accurately. Elements that are too small may require more precision than some users can provide.

• SwiftUI Solution: Set minimum touch sizes by adding padding or using .frame(minWidth:minHeight:) to ensure a comfortable touch target size.

• Example:

    Button(action: { /* Action */ }) {
        Text("Tap Me")
            .frame(minWidth: 44, minHeight: 44)
    }.padding()
  

• Testing: Manually interact with touch elements in the app on an iOS device. Ensure they are easily tappable without precise effort. Verify touch target size with the Accessibility Inspector to confirm they meet recommended minimums (44x44 points).

Inaccessible Navigation

• Challenge: Apps with limited navigability can cause frustration for users who rely on screen readers or keyboards. Without a clear reading order, navigating through the interface becomes challenging.

• SwiftUI Techniques for Accessible Navigation:

  • Group Elements with .accessibilityElement(children:): Combine related elements into a single accessible unit for more streamlined navigation.

      VStack {
          Text("Profile")
          Image("profile_picture")
      }
      .accessibilityElement(children: .combine)
    

  • Set Focus with .accessibilityFocused: Programmatically control focus on specific elements.

      Text("Special Announcement")
          .accessibilityFocused($isFocused)
    

  • Custom Actions with .accessibilityAction: Add specific actions for interactive controls like sliders or steppers.

      Slider(value: $value)
          .accessibilityAction(named: "Increase") { value += 10 }
    

  • Hide Decorative Elements with .accessibilityHidden: Exclude non-essential visuals from screen readers.

      Image("decorative_image")
          .accessibilityHidden(true)
    

• Testing: Enable VoiceOver and use swipe gestures to confirm the intended focus order. Also, use a connected keyboard or switch control to test smooth transitions and confirm navigability.

Lack of Feedback for Actions

• Challenge: Without feedback, users with visual or hearing impairments may struggle to confirm if an action has completed. Feedback like haptic, auditory, or visual cues can enhance usability.

• SwiftUI Solution: Use .accessibilityHint to provide additional information about the action that will occur.

• Example:

    Button("Submit") {
        // Submit action
    }.accessibilityHint("Submits the form")
  

• Testing: Use VoiceOver to ensure that hints are read immediately after labels. Check that users can understand what each button does without extra explanation.

Complex or Confusing User Interfaces

• Challenge: Cluttered interfaces can be overwhelming, particularly for users with cognitive impairments, who may struggle to navigate or process information effectively.

• SwiftUI Solution: Simplify layouts and use .accessibilitySortPriority to organize the reading order logically.

• Example:

    VStack {
        Text("Main Content")
            .accessibilitySortPriority(1)
        Button("Secondary Action")
            .accessibilitySortPriority(2)
    }
  

• Testing: Use VoiceOver to verify the logical reading order and ensure only relevant elements are accessible. Use .accessibilityHidden to hide decorative elements that do not add meaningful information.

Lack of Support for Assistive Technologies

• Challenge: Inadequate support for screen readers or other assistive technologies can make apps unusable for some users.

• SwiftUI Solution: Group elements with .accessibilityElement(children: .combine) for cohesive navigation. This improves readability and usability for screen reader users.

• Example:

    VStack {
        Text("Profile")
        Image("profile_picture")
    }
    .accessibilityElement(children: .combine)
  

• Testing: Check with VoiceOver that grouped elements are announced as a single unit, improving navigation flow for visually impaired users.

Poorly Implemented Accessibility Features

• Challenge: Without regular testing and updates, accessibility features can degrade over time, negatively impacting the user experience.

• SwiftUI Solution: Regular testing with VoiceOver and Xcode’s Accessibility Inspector helps maintain effective functionality.

• Testing: Conduct regular testing to detect regressions or improvements needed for accessibility. Recheck VoiceOver usability after UI updates to confirm features remain effective.

Insufficient Customization Options

• Challenge: Limited customization options, such as font size or color schemes, restrict usability for users with specific visual needs.

• SwiftUI Solution: Use .dynamicTypeSize() to allow text scaling based on the user’s preferred settings.

• Example:

    Text("Adjustable Text")
        .dynamicTypeSize(.xxxLarge)
  

• Testing: Adjust text size in iOS Accessibility settings, and ensure the app’s text scales correctly without truncating or overlapping, preserving readability.

References

1. Apple Developer Documentation: SwiftUI Accessibility

   • Comprehensive guide to accessibility in SwiftUI, covering accessibility properties like .accessibilityLabel, .accessibilityHint, .accessibilityElement, and more.

   • SwiftUI Accessibility Guide

2. Apple Human Interface Guidelines: Accessibility

   • Apple's best practices for designing accessible apps, including color contrast and touch target size recommendations.

   • Apple Human Interface Guidelines: Accessibility

3. Color Contrast Analyzer

   • A tool for testing contrast ratios to ensure color accessibility compliance with WCAG standards.

   • Color Contrast Analyzer

4. VoiceOver and Accessibility Inspector

   • Tools for testing accessibility features, available in iOS and Xcode for simulating screen reader usage and checking accessibility properties.

   • VoiceOver Documentation

   • Accessibility Inspector Documentation

5. Chandarana, N., & Gada, T. (2024). Accessibility Challenges in Current Mobile Applications: A Comprehensive Overview.

   • This journal paper provides an in-depth analysis of common accessibility challenges faced in mobile applications, discussing real-world examples and potential solutions for developers.

   • International Journal of Innovative Research in Computer and Communication Engineering.

In this article we will talk about why and how to implement the GameCenter's Leaderboard within your app.

Why GameCenter is Making a Huge Revival

You can make iPhone games without a scoreboard, but leaderboards can help make the game feel more competitive, like people are competing against one another around the World.

Instead of creating and managing your own backend, the GameCenter Leaderboard allows you to scale with traffic infinitely, skip an entire login page for authorization, get the Image, Name, and friends playing the same game – all without your users having to enter anything.

Especially with iOS 16, Apple is investing more in improving it, and driving more app usage, like through Push Notifications when your friend beats your score in the game.

In my journey of learning SwiftUI, I have been creating and publishing apps, because IMO that's the best way to learn.

There wasn't much updated documentation on how to do a lot of this, especially none with SwiftUI nor with the advent of async and await in Swift. So I consolidated and simplified it for everyone to build amazing apps. So feel free to invite me to test your apps too!

Pre-Requisites:

• You'll need to have an Apple Developer paid account
• You have to create the App Id for your app in the provisioning profiles section of the Apple Developer Portal
• You have to create the App in the iTunes Connect Connect portal

How to Implement Your iOS Leaderboard in 6 Steps

Most of the code logic for the leaderboard is in this file if you want to skip ahead. Here's the steps as follows:

1. How to Create the App Store Connect Leaderboard

Screenshot from the Apple iTunes Connect Portal

Once you have created the app in the App Store Connect portal successfully, go to the Services tab for the app -> and make sure you're in the GameCenter page.

Then add a new leaderboard using the "+" sign, which can either be "Classic" (scores never reset) or "Recurring" (scores reset based on your frequency settings).

Most games prefer a recurring leaderboard so that the leaderboard isn't cluttered with older impossible to reach high scores.

The LeaderboardID you input there is the one that you need to use in all the places in the code that ask for it.

Details required to create a new Leaderboard

2. How to Set Up GameCenter Authentication

First, you'll need to authenticate users to GameCenter in order for any of this functionality to work.

So we'll use this code to do that, which basically makes sure that you (GKLocalPlayer.local) are authenticated, or prints an error if there is one:

func authenticateUser() {
    GKLocalPlayer.local.authenticateHandler = { vc, error in
        guard error == nil else {
            print(error?.localizedDescription ?? "")
            return
        }
    }
}

If the user is authenticated, you will see a little popup in the UI. If not, the user will be taken to a page to login to their GameCenter account.

A sign that displays when a user is logged in

3. How to Display Leaderboard Items in the UI

In order to get the data away from the GameCenter ViewController leaderboards (GKLeaderboard), you need to use the loadLeaderboards .

You can switch up the loadEntries function from .global to .friends in order to only pull your friends.

You can also retrieve the image for each player by iterating over each player and performing a loadPhoto.

Using NSRang(1...5), you can choose how many players to display. This pulls the users with the highest 5 scores from the leaderboard and returns none if there's no users, such as in the case when the cycle refreshes for a recurring Leaderboard.

This is what pulling data from a leaderboard could look like if you take advantage of async-await:

func loadLeaderboard() async {
    playersList.removeAll()
    Task{
        var playersListTemp : [Player] = []
        let leaderboards = try await GKLeaderboard.loadLeaderboards(IDs: [leaderboardIdentifier])
        if let leaderboard = leaderboards.filter ({ $0.baseLeaderboardID == self.leaderboardIdentifier }).first {
            let allPlayers = try await leaderboard.loadEntries(for: .global, timeScope: .allTime, range: NSRange(1...5))
            if allPlayers.1.count > 0 {
                try await allPlayers.1.asyncForEach { leaderboardEntry in
                    var image = try await leaderboardEntry.player.loadPhoto(for: .small)
                    playersListTemp.append(Player(name: leaderboardEntry.player.displayName, score:leaderboardEntry.formattedScore, image: image))
                                print(playersListTemp)
                    playersListTemp.sort{
                        $0.score < $1.score
                    }
                }
            }
        }
        playersList = playersListTemp            
    }
}

You can get leaderboard data into your app

4. How to Call Functionality in SwiftUI as the View/Page Appears

You can take advantage of the onAppear lifecycle function of the view to actually make the calls to authenticate and load, but you can also do it on the tap of a button if you prefer that:

.onAppear(){
    if !GKLocalPlayer.local.isAuthenticated {
        authenticateUser()
    } else if playersList.count == 0 {
        Task{
            await loadLeaderboard()
        }
    }
}

5. How to Load the Submitted Scores

In order to load the scores, you need to submit them as well. The submitScore function can help you with that.

• The flightsClimbed variable should contain the score that you would like to submit.
• GameKit makes sure to only display your best score for the life of the leaderboard.
• The leaderboardId contains the value that you manually enter in your App Store Connect account:

func leaderboard() async{
    Task{
        try await GKLeaderboard.submitScore(
            flightsClimbed,
            context: 0,
            player: GKLocalPlayer.local,
            leaderboardIDs: ["com.tfp.stairsteppermaster.flights"]
        )
    }
    calculateAchievements()
}

6. How to display the GameCenter ViewController Portal

When you're logged into GameCenter, a little annoying icon appears in the top right of your screen. When you tap on it, you are taken to the GameCenter ViewController. Luckily you can hide it if it's not part of your design, using GKAccessPoint.shared.isActive = false.

Since the GameCenter UI is a UIKit ViewController and not a simple SwiftUI View, you need to create this UIViewControllerRepresentable first (as you can see here), to launch GameCenter using a different button,

Once you add that file to your project, you can display the GameCenter portal simply using this: GameCenterView(format: gameCenterViewControllerState) where gameCenterViewControllerState can be help you go to a detail page in GameCenter.

GameCenter's Leaderboard View

Things to Keep in Mind While using GameCenter's Leaderboards:

• Simulator Debugging – For some reason the authenticate to GameCenter is extremely slow on a simulator, so it might make sense to even create a mock of data when using the simulator.
• Challenges – You can't programmatically issue GameKit Challenges to your friends anymore due to deprecation. Instead, you have to do those manually within the user's GameCenter dashboard against GameKit Achievements. Also, there's no way to view challenges you have sent.
• Achievements – Leaderboards are different from the GameKit Achievements, which is calculated and displayed differently, but a lot easier. Those can also be pulled into the app as well, as you can see below:

GameKit Challenges and Achievements

Wrapping Up

You can try out the free open-source Stair Master Climber iPhone Health & Fitness app that I shared above. I would love to know what you think so that we can learn together.

Feel free to reach out to me on social media or by email if you have any questions.

In this tutorial for beginners, you will learn the basics of using SwiftUI to make API calls using the popular Internet Chuck Norris DataBase (ICNDB) as an example. It will display a joke quickly and easily using Swift and SwiftUI.

You'll see how the cross-platform framework SwiftUI lets us use the exact same code across iOS, iPadOS, macOS, watchOS, App Clips and tvOS, which otherwise would have been impossible.

Along with that, you will use async-await that was introduced in Swift 5.5, which works for newer operating systems including iPhones running iOS > v15.0. This really simplifies our work of making data network calls asynchronously on click of a button without freezing the UI thread.

I will share the code changes you'll need to make first. Then in the following section, I will share a brief analysis of the code so beginners can understand what's going on as well.

tvOS app running the code displays a button that retrieves the joke on click

How to Make API Calls in Swift and SwiftUI

First, you'll need a Mac to install Xcode. Once it's installed, open Xcode and create a new project. Then select "App" for iOS, macOS, tvOS, or watchOS.

ContentView

Just update your existing ContentView SwiftUI file to add a Button and use the State variable to refresh the text displayed as the joke returns from ICNDB API:

import Foundation
import SwiftUI
struct ContentView: View {
    @State private var joke: String = ""
    var body: some View {
        Text(joke)
        Button {
            Task {
                let (data, _) = try await URLSession.shared.data(from: URL(string:"https://api.chucknorris.io/jokes/random")!)
                let decodedResponse = try? JSONDecoder().decode(Joke.self, from: data)
                joke = decodedResponse?.value ?? ""
            }
        } label: {
            Text("Fetch Joke")
        }
    }
}
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}
struct Joke: Codable {
    let value: String
}

Fetch a joke!

If you press build/play, the app will build in whatever platform you selected above:

Screenshots of watchOS, macOS, and iOS apps running the same exact code

Code Analysis

If you go to the random joke URL, you'll notice that the data is in JSON format. You can copy that and use a JSON Linter to view its structure to figure out what property of the Joke object is needed.

Based on that, you determine the code above. You use the Codable protocol (aka interfaces) to go from a JSON data object to an actual Swift class or struct, and you create properties for the data you want to store (value in our case).

JSONDecoder helps us parse the JSON string using the Codable object. This works regardless of platform because the page that loads on launching the app has the same name ContentView regardless of platform.

App Clips

App Clips are Apple's latest way of using native app functionality using an "App Clip Code" without having to download the whole application from the App Store.

App Clips work similar to an iOS app – the only difference is that you don't create a new App Clip project. You just need to add the App Clip as a target to an existing iOS app by going to File->New->Target->iOS->App Clip when an existing iOS app is open in Xcode.

If you you wondering about iPhone/iPad Widgets, well they don't animate. So button clicks will just open the corresponding app and can't update text through an external API independently.

Conclusion

In this article, you learned how to make RESTful GET API calls from SwiftUI in the simplest possible way!

Feel free to reach out to me if you have any questions. I figured this out using another article and I thought of simplifying it further. So for more details and ways to make this code more complex, check out that article:

Building a design system to support one product is not easy - it has to be robust and flexible at the same time for scalability. Though challenging, lots of great resources have shared useful principles and approaches that help teams build a good system both visually and programmatically. Standing on their shoulders, this article tries to contribute to an untouched ground by focusing on building a good system in SwiftUI.

Why do I write this article

During my first summer in ITP at New York, I'm lucky to have the opportunity to work as an iOS developer intern at Line Break Studio. One task I've been assigned to is building a design system in two steps: first visually in Sketch, and then programmatically in SwiftUI. The experience of experimenting with the new framework and building a design system with it has been amazing, but also buggy along the way. That's why we'd like to share our experience with the community, hopefully making your development process easier.

What is SwiftUI

Apple released this groundbreaking new framework in WWDC 2019, which is one of the bests in years. From the point of view as a web developer, the project development experience in SwiftUI is closer to which in conventional front-end stack and frameworks.

This is definitely an awesome move because programming interface and managing states are drastically easier than before. And the best part of this improvement is that one can integrate UIKit and SwiftUI smoothly. To learn the basics of SwiftUI, the official tutorials provided by Apple are very helpful.

The demo project

For demonstration purpose, I put up a simplified version of design system we built in Line Break Studio. It a set of button components in different forms, which are built on top of two lower level parts: typography and colorPalette.

Dynamic rendering view of the demo project

The project is public on GitHub, and I'm using Xcode 11 Beta 5 for development. An Airtable base as design system management hub (read more about workflow management) is also public for reference.

Principles of building design system

Design system in code is a middleware between designers and developers. Developer of the system takes inputs from design system in visual form, and produces API that's identical with which for further development. Following two principles should be recognized to complete this system in code:

1. Communicate with tokens

Fundamentally, the purpose of having a design system in program is not about better code management or development efficiency, but to make sure the view is consistent with design files. To achieve that goal, using tokens to signify certain color, font, size or any visual elements is crucial to maintain quality of communication between developers, designers and managers in a team.

Lightning Design System's tokens built by Salesforce

2. Levels of hierarchy

In EightShapes' article, it points out that we should "Show options first, then decisions next", because "You can't make decisions without options."

EightShapes' article about design tokens

This kind of ordering architecture loosens the degree of coupling between different levels, hence providing more flexibility and dynamic for possible revisions. The way I structure the levels is in this order from bottom to top: material → base → token. But it could be anyway the team's comfortable with.

Diving into code

Following section is a list of highlights we'd like to point out based on our experience. Please visit the GitHub repo for complete code. Any feedbacks or critics are welcome for improvements.

1. Architecting levels of hierarchy

There're two ways of stacking materials at lower level to construct tokens at highest level:

• Use enum for type safety and code literacy

Advantages of using enum in code as grouping wrapper or parameter in function have already been well recognized. One point worths mentioning here is the implementation of levels of hierarchy.

We always store the raw values, including font size (CGFloat) and font name (String), at the lowest level, because we don't want to mess around with it. But because raw value must be a literal in enum, we can't just assign a case to be a value from the other enum.

To work around this problem, we implement a function getValue, which returns the raw value in switch case when necessary.

• Use struct for easier structure

Though enum is great, we don't need its unique feature in some cases. For example, because Xcode takes care of the heavy job of processing dynamic colors, and no parameter options are required in API endpoint, we can set up color palettes by simple two levels of struct.

2. Clear and straightforward naming of API endpoint

Naming convention is another broad topic for discussion and debate. In addition to basic Swift conventions, the only two rules we abide are, 1) no acronym and 2) making it simple. For example, to use typography and color system, instead of creating new endpoints, we make extension from Font and Color structs. This approach decreases the effort to memorize unfamiliar API names for developers.

3. Manage color sets dynamically in two modes

So dark mode has become a standard in industry, and both iOS and Android team have implemented this feature. It's a good trend for users, but could bring designers and developers some challenges, including managing and naming the color sets, especially gray scale ones.

Material Design's dark theme guide

To think and communicate about gray scale colors dynamically, using terms like white, light, black or dark doesn't work. Because if we referred to a dynamic color #000000 (black in HEX) black or dark in light color scheme, how do you talk about this particular color, which should turn into #FFFFFF (white in HEX), in dark color scheme? defaultDark or lightDark?

Confusing transition of color sets

It is very confusing to name gray scale dynamic color sets in conventional approach. To avoid this confusion, we use theme and contrast to manage one set of color in light and dark schemes instead.

Example color naming in demo Airtable base

Note that a gray scale color doesn't always need to be reversed in opposite color mode. In these situations that light color remains light and dark remains dark, we simply name name it light or dark instead.

Once we wrap our head around this naming method, managing this architecture of color palette is easy in Xcode. To create a color set, simply create a new Asset Catalog file → add a new Color Set → and change Appearances to Any, Light, Dark will do.

How to add color asset in Xcode

4. environment settings

One awesome feature in SwiftUI framework is the environment modifier, which provides ability to control environment values on target view. In terms of building design system, this ability provides convenient approach to change app's font at root level. And the other advantage of using environmentValue is to change and test light and dark color schemes in development.

5. buttonStyle and button label

Comparing to the old days in UIKit, constructing reusable buttons in SwiftUI is drastically easier. The Button view consists of two parts, which are action closure (event to be fired as button is pressed) and label (body of the button). The view can then be chained with a modifier buttonStyle. To learn details about building reusable buttons,I recommend reading Alejandro's tutorial, which is comprehensive and useful.

In our customized button components, first step is to create two structs, including TokenButtonLabel and TokenButtonStyle. These two structs are programmed according to the types of buttons we have in design files. For example, there're only two types of labels: icon and text. Each type has an according init function designed with different parameters for new instances.

On the other hand, there're four major types of button styles: circle icon, icon, capsule and text. To follow ButtonStyle protocol, a makeBody func has to be implemented. This function brings us a configuration property, providing a native isPressed value to monitor if the button is pressed or not.

Finally, stacking on top of TokenButtonLabel and TokenButtonStyle, the endpoint of the button component API will be TokenButton - a grouping that wraps content and style of button together, conforming to the button types in visual design system.

6. AnyView as wrapper

As we're dealing with the makeBody function brought by ButtonStyle protocol, we found a useful tip to work with View. To store a view in a variable, the type annotation could be indicated as AnyView, which works as a general container of views in SwiftUI.

In our case, because we want to add the opacity modifier to configuration.label to all types of buttons, instead of doing so repeatedly in each switch case, it makes more sense to chain the modifier at the end altogether. We can achieve this pattern by using the advantage of AnyView in this way:

7. Build view modifier with mutating function

To update styles of the buttons dynamically, we can build our own modifier. First instantiate customized mutable state properties in view, and then create a mutating function which returns a Self type after updating the target state property.

8. Tricky border style

One drawback of SwiftUI is styling a circle shape with circular border is not straightforward at all. I struggled for a while, and finally found a solution here on StackOverflow. A clipShape and an overlay modifier are required to make it work.

Conclusion

SwiftUI is an incredible improvement Apple makes. Though flaws still exist, building a robust and flexible design system with it, and furthermore complicated UI in iOS is way efficient than ever. I hope this article is helpful for any iOS team trying to build UI, and always welcome to any feedbacks!

? Read more of my works at vinceshao.com / Follow me on Twitter or LinkedIn