apple / apple/swift-openapi-generator

Add more examples of nameOverrides to docs

Open
#771 3 comments 0 reactions 0 assignees View on GitHub
area/documentation kind/enhancement
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

### Question

I'm using the generator against App Store Connect API. I have the namingStrategy set to idiomatic and this produces really fun parameters such as the /v1/apps filter parameter of

```swift
public init(
filter_lbrack_name_rbrack_: [Swift.String]? = nil,
filter_lbrack_bundleId_rbrack_: [Swift.String]? = nil,
filter_lbrack_sku_rbrack_: [Swift.String]? = nil,

```

The API is riddled with filter[_something_] query parameters so I'm not entirely sure if I want to sign up for the endeavor, but, gotta get one rename to work. I am not finding much in the way of documentation here so I could be doing something entirely wrong or simply not supported.
https://github.com/search?q=repo%3Aapple%2Fswift-openapi-generator%20nameOverrides&type=code

This is the only reference I could find showing an example: https://github.com/apple/swift-openapi-generator/blob/0bd6d842f7f25047d024fdb6e2b9b8ce932518c2/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0013.md?plain=1#L143-L147

So I tried this, but without any success.

```yaml
nameOverrides:
'filter_lbrack_name_rbrack_': 'filterName'
```

Here is an excerpt from the ASC open api spec:

```yaml
/v1/apps:
get:
tags:
- Apps
operationId: apps_getCollection
parameters:
- name: filter[name]
in: query
description: filter by attribute 'name'
schema:
type: array
items:
type: string
style: form
explode: false
required: false
- name: filter[bundleId]
in: query
description: filter by attribute 'bundleId'
schema:
type: array
items:
type: string
style: form
explode: false
required: false
- name: filter[sku]
in: query
description: filter by attribute 'sku'
schema:
type: array
items:
type: string
style: form
explode: false
required: false
```

Contributor guide

Open the contributing guide

Research direction

Start with Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0013.md, especially the existing nameOverrides example, and compare it with the generated filter parameter names described in the issue. Add documentation examples that clarify how to override these names, including the App Store Connect-style filter parameters. Done means a newcomer can understand the supported syntax and apply it to the shown case.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.