Add ability to prevent generation of deprecated APIs and components

[edorphy]

Motivation

I'd like the ability to use a feature flag or some other construct to instruct the generator to ignore deprecated specification sections.

For a project that is using the generator net-new, this will immediately setup the project to use the modern API or replacement API when something is deprecated. Why generate deprecated source if it is known to be unnecessary from the start, right?

Proposed solution

I could see this happening via two different paths, either a modification to the configuration to add another check or a feature flag. Either way, it allows someone to opt-into the behavior so it would be backwards compatible with teams that generated in the past using the tool.

ignoreDeprecations: true

or by defining a new feature case: https://github.com/apple/swift-openapi-generator/blob/main/Sources/_OpenAPIGeneratorCore/FeatureFlags.swift

Alternatives considered

1. Modify the OpenAPI spec file stripping out any deprecations
2. Modify the generated source deleting any deprecations
3. Using the filters which seems to be include behavior only, not exclude behavior so I don't think this would work

1 and 2 go against the nature of ''generating" from source, 3 doesn't seem to be possible.

Additional information

Similar to: #715

The intent behind this feature request is to prevent teams from calling deprecated methods to begin with. I believe this to be different than #715 because that one looks to prevent the deprecation indications from being emitted. I don't want the function, type, etc., to even exist.

Preventing deprecated API calls to any framework can be done via linters and other tools. However, the generated code still exists. While I don't expect someone to read all of the generated code, the fact that it exists allows a developer to go and read about it--no different than reading the original documentation or viewing the OpenAPI spec, yes, but this is just another point of visibility.

Plus on top of that, you can easily suppress using deprecated APIs in linters and then it becomes a team culture thing to not allow that.

[czechboy0]

Hi @edorphy,

yeah this has been discussed a few times, and one of the reasons for the hesitation to implement it in the generator is that what you're asking for you can perform on the OpenAPI document before you ever pass it to this generator. There's a wealth of tools for modifying OpenAPI documents in various ways (check out openapi.tools, for example), and we don't want to reimplement and (more importantly) maintain code that does the same as existing OSS tools.

Can you give some of those tools a try and see if that fits into your workflow? It's certainly how the OpenAPI ecosystem is meant to work, rather than OpenAPI generators reimplementing too much functionality covered by other focused tools.