Use the package access modifier for generated code (#393)

### Motivation

Fixes #270.

The `package` access modifier seems like the right default access
modifier for generated code, as it forces adopters to explicitly opt
into generated APIs leaking outside of their package. `internal` was too
limiting, as often you want to isolate generated code into a separate
module. Fortunately, Swift 5.9 provided that feature and since 1.0 will
ship with 5.9 as minimum Swift version, we can switch to `package` as
default.

### Modifications

- (Re)added the ability to customize the access modifier of the
generated code. You can do so from the config file and with a CLI
option.
- The default has changed from `public` to `package` (a breaking
change).
- Updated docs (some drive-by docs improvements as well for which
OpenAPI features are supported.)

### Result

Generated code uses the `package` access modifier by default, but the
user can change it to `public` or `internal`, if needed.

### Test Plan

Manually tested the CLI path, the config file path, updated tests, but
didn't actually change our fixtures, as there's no need. We just
explicitly override to `public`.

I also tried this branch on a real-world document using the generator
plugin, and tried all 3 access modifiers and verified all 3 worked (the
project built successfully).

Author: czechboy0

Sources/_OpenAPIGeneratorCore/Config.swift

@@ -23,6 +23,12 @@ public struct Config: Sendable {
     /// The generator mode to use.
     public var mode: GeneratorMode
 
+    /// The access modifier to use for generated declarations.
+    public var access: AccessModifier
+
+    /// The default access modifier.
+    public static let defaultAccessModifier: AccessModifier = .package
+
     /// Additional imports to add to each generated file.
     public var additionalImports: [String]
 
@@ -35,23 +41,21 @@ public struct Config: Sendable {
     /// Creates a configuration with the specified generator mode and imports.
     /// - Parameters:
     ///   - mode: The mode to use for generation.
+    ///   - access: The access modifier to use for generated declarations.
     ///   - additionalImports: Additional imports to add to each generated file.
     ///   - filter: Filter to apply to the OpenAPI document before generation.
     ///   - featureFlags: Additional pre-release features to enable.
     public init(
         mode: GeneratorMode,
+        access: AccessModifier,
         additionalImports: [String] = [],
         filter: DocumentFilter? = nil,
         featureFlags: FeatureFlags = []
     ) {
         self.mode = mode
+        self.access = access
         self.additionalImports = additionalImports
         self.filter = filter
         self.featureFlags = featureFlags
     }
 }
-
-extension Config {
-    /// Returns the access modifier to use for generated declarations.
-    var access: AccessModifier? { .public }
-}

Sources/_OpenAPIGeneratorCore/Layers/StructuredSwiftRepresentation.swift

@@ -50,11 +50,14 @@ struct ImportDescription: Equatable, Codable {
 /// A description of an access modifier.
 ///
 /// For example: `public`.
-enum AccessModifier: String, Equatable, Codable {
+public enum AccessModifier: String, Sendable, Equatable, Codable {
 
     /// A declaration accessible outside of the module.
     case `public`
 
+    /// A declaration accessible outside of the module but only inside the containing package or project.
+    case `package`
+
     /// A declaration only accessible inside of the module.
     case `internal`
 

Sources/_OpenAPIGeneratorCore/Renderer/TextBasedRenderer.swift

@@ -175,6 +175,7 @@ struct TextBasedRenderer: RendererProtocol {
     func renderedAccessModifier(_ accessModifier: AccessModifier) -> String {
         switch accessModifier {
         case .public: return "public"
+        case .package: return "package"
         case .internal: return "internal"
         case .fileprivate: return "fileprivate"
         case .private: return "private"

Sources/swift-openapi-generator/Documentation.docc/Articles/Configuring-the-generator.md

@@ -30,6 +30,10 @@ The configuration file has the following keys:
     - `types`: Common types and abstractions used by generated client and server code.
     - `client`: Client code that can be used with any client transport (depends on code from `types`).
     - `server`: Server code that can be used with any server transport (depends on code from `types`).
+- `accessModifier` (optional): a string. Customizes the visibility of the API of the generated code.
+    - `public`: Generated API is accessible from other modules and other packages (if included in a product).
+    - `package` (default): Generated API is accessible from other modules within the same package or project.
+    - `internal`: Generated API is accessible from the containing module only.
 - `additionalImports` (optional): array of strings. Each string value is a Swift module name. An import statement will be added to the generated source files for each module.
 - `filter`: (optional): Filters to apply to the OpenAPI document before generation.
     - `operations`: Operations with these operation IDs will be included in the filter.
@@ -38,7 +42,6 @@ The configuration file has the following keys:
     - `schemas`: These (additional) schemas will be included in the filter.
 - `featureFlags` (optional): array of strings. Each string must be a valid feature flag to enable. For a list of currently supported feature flags, check out [FeatureFlags.swift](https://github.com/apple/swift-openapi-generator/blob/main/Sources/_OpenAPIGeneratorCore/FeatureFlags.swift).
 
-
 ### Example config files
 
 To generate client code in a single target:
@@ -73,6 +76,16 @@ additionalImports:
   - APITypes
 ```
 
+To use the generated code from other packages, also customize the access modifier:
+
+```yaml
+generate:
+  - client
+additionalImports:
+  - APITypes
+accessModifier: public
+```
+
 ### Document filtering
 
 The generator supports filtering the OpenAPI document prior to generation, which can be useful when

Sources/swift-openapi-generator/Documentation.docc/Articles/Manually-invoking-the-generator-CLI.md

@@ -40,6 +40,8 @@ To see the usage documentation for the generator CLI, use the following command:
 % swift run swift-openapi-generator --help
 ```
 
+> Note: By default, the code is generated with the `package` access modifier, to make the generated code visible from other packages, add `--access-modifier public` to the invocation.
+
 ### Use the Swift package command
 
 As an alternative to invoking the CLI manually, you can also use the package command, which works similarly to the build plugin.

Sources/swift-openapi-generator/Documentation.docc/Articles/Supported-OpenAPI-features.md

@@ -22,8 +22,8 @@ For any other formats, the payload is provided as raw bytes, leaving it up to th
     - when content type is `application/json` or ends with `+json`
 - [x] URL-encoded form request bodies
     - when content type is `application/x-www-form-urlencoded`
-- [ ] multipart
-    - tracked by [#36](https://github.com/apple/swift-openapi-generator/issues/36)
+- [x] multipart
+    - for details, see [SOAR-0009](https://swiftpackageindex.com/apple/swift-openapi-generator/main/documentation/swift-openapi-generator/soar-0009)
 - [ ] XML
 
 ### OpenAPI specification features
@@ -63,21 +63,21 @@ For any other formats, the payload is provided as raw bytes, leaving it up to th
 
 - [x] url
 - [x] description
-- [ ] variables
+- [x] variables
 
 #### Server Variable Object
 
-- [ ] enum
-- [ ] default
-- [ ] description
+- [x] enum
+- [x] default
+- [x] description
 
 #### Paths Object
 
 - [x] map from pattern to Path Item Object
 
 #### Path Item Object
 
-- [ ] $ref
+- [x] $ref
 - [x] summary
 - [x] description
 - [x] get/put/post/delete/options/head/patch/trace
@@ -110,7 +110,7 @@ For any other formats, the payload is provided as raw bytes, leaving it up to th
 - [x] schema
 - [ ] example
 - [ ] examples
-- [ ] encoding
+- [x] encoding (in multipart only)
 
 #### Security Requirement Object
 
@@ -198,8 +198,8 @@ For any other formats, the payload is provided as raw bytes, leaving it up to th
 
 #### Encoding Object
 
-- [ ] contentType
-- [ ] headers
+- [x] contentType
+- [x] headers
 - [ ] style
 - [ ] explode
 - [ ] allowReserved

Sources/swift-openapi-generator/GenerateOptions+runGenerator.swift

@@ -30,11 +30,13 @@ extension _GenerateOptions {
     func runGenerator(outputDirectory: URL, pluginSource: PluginSource?, isDryRun: Bool) async throws {
         let config = try loadedConfig()
         let sortedModes = try resolvedModes(config)
+        let resolvedAccessModifier = resolvedAccessModifier(config)
         let resolvedAdditionalImports = resolvedAdditionalImports(config)
         let resolvedFeatureFlags = resolvedFeatureFlags(config)
         let configs: [Config] = sortedModes.map {
             .init(
                 mode: $0,
+                access: resolvedAccessModifier ?? Config.defaultAccessModifier,
                 additionalImports: resolvedAdditionalImports,
                 filter: config?.filter,
                 featureFlags: resolvedFeatureFlags

Sources/swift-openapi-generator/GenerateOptions.swift

@@ -28,6 +28,11 @@ struct _GenerateOptions: ParsableArguments {
             "The Swift files to generate. Options: \(GeneratorMode.prettyListing). Note that '\(GeneratorMode.client.rawValue)' and '\(GeneratorMode.server.rawValue)' depend on declarations in '\(GeneratorMode.types.rawValue)'."
     ) var mode: [GeneratorMode] = []
 
+    @Option(
+        help:
+            "The access modifier to use for the API of generated code. Default: \(Config.defaultAccessModifier.rawValue)"
+    ) var accessModifier: AccessModifier?
+
     @Option(help: "Additional import to add to all generated files.") var additionalImport: [String] = []
 
     @Option(help: "Pre-release feature to enable. Options: \(FeatureFlag.prettyListing).") var featureFlag:
@@ -38,6 +43,8 @@ struct _GenerateOptions: ParsableArguments {
     ) var diagnosticsOutputPath: URL?
 }
 
+extension AccessModifier: ExpressibleByArgument {}
+
 extension _GenerateOptions {
 
     /// The user-provided user config, not yet resolved with defaults.
@@ -58,6 +65,15 @@ extension _GenerateOptions {
         return Set(config.generate).sorted()
     }
 
+    /// Returns the access modifier requested by the user.
+    /// - Parameter config: The configuration specified by the user.
+    /// - Returns: The access modifier requested by the user, or nil if the default should be used.
+    func resolvedAccessModifier(_ config: _UserConfig?) -> AccessModifier? {
+        if let accessModifier { return accessModifier }
+        if let accessModifier = config?.accessModifier { return accessModifier }
+        return nil
+    }
+
     /// Returns a list of additional imports requested by the user.
     /// - Parameter config: The configuration specified by the user.
     /// - Returns: A list of additional import statements requested by the user.

Sources/swift-openapi-generator/UserConfig.swift

@@ -23,6 +23,9 @@ struct _UserConfig: Codable {
     /// A list of modes to use, in other words, which Swift files to generate.
     var generate: [GeneratorMode]
 
+    /// The access modifier used for the API of generated code.
+    var accessModifier: AccessModifier?
+
     /// A list of names of additional imports that are added to every
     /// generated Swift file.
     var additionalImports: [String]?
@@ -38,6 +41,7 @@ struct _UserConfig: Codable {
 
     enum CodingKeys: String, CaseIterable, CodingKey {
         case generate
+        case accessModifier
         case additionalImports
         case filter
         case featureFlags

Tests/OpenAPIGeneratorCoreTests/Parser/Test_YamsParser.swift

@@ -163,7 +163,7 @@ final class Test_YamsParser: Test_Core {
         try YamsParser()
             .parseOpenAPI(
                 .init(absolutePath: URL(fileURLWithPath: "/foo.yaml"), contents: Data(yaml.utf8)),
-                config: .init(mode: .types),
+                config: .init(mode: .types, access: Config.defaultAccessModifier),
                 diagnostics: PrintingDiagnosticCollector()
             )
     }