apple / apple/swift-openapi-generator

Generate types for the path string

Open
#668 2 comments 1 reaction 0 assignees View on GitHub
kind/feature status/triage
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

### Motivation

```yaml
paths:
/greet:
get:
operationId: getGreeting
/count:
get:
operationId: getCount
```

The actual path of the endpoints that we define is only used in the comment or documentation of the operations. It would be useful to have the string of the path, `/greet` and `/count` in the above example, available in the Swift code as well.

One use case that I encountered was when I was making a request to a third-party API. I provide a webhook URL, meaning when the third party finishes, they will call back my endpoint that I defined in my OpenAPI YAML file for the webhook requests. In this case, I need to pass this path to this third-party provider. It would be nice to have it type-safe from changes in the OpenAPI path namings.

### Proposed solution

For the simple paths this can be straightforward a constant in the Operations enum. But for the paths that have parameters in them, we might use a simple function with path parameters as its arguments.

```swift
public enum Operations {
public enum greet {
public static let path = "/greet"
// ...
}
}
```

If we have a yaml like

```yaml
paths:
/users/{userId}:
get:
operationId: getUser
```

then

```swift
public enum Operations {
public enum getUser {
public static let path: @Sendable (String) -> String = { "/users/\($0)" }
// ...
}
}
```

we can make use of the type of the path parameter

```yaml
paths:
/users/{id}:
get:
operationId: getUser
parameters:
- in: path
name: id
required: true
schema:
type: integer
minimum: 1
```

```swift
public enum Operations {
public enum getUser {
public static let path: @Sendable (Int) -> String = { "/users/\($0)" }
// ...
}
}
```

### Alternatives considered

_No response_

### Additional information

_No response_

Contributor guide

Open the contributing guide

Research direction

The issue names no files or tests; start by locating the generator code that emits operation enums and handles path parameters. Compare the simple and parameterized OpenAPI examples, then define completion as generated Swift exposing each operation's path with type-safe parameter handling.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, swift
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.