diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md index 81bba3d1..f308a646 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-generated-code.md @@ -27,7 +27,7 @@ Below is a table of example changes you might make to an OpenAPI document, and w | Remove a required property | ❌ | ❌ | ❌ | | Rename a schema | ✅ | ❌ | ❌ | -> †: Safe change to make as long as no adopter captured the Swift function signature of the initializer of the generated struct, which gains a new parameter. Rare, but something to be aware of. +> †: Safe change to make as long as no adopter captured the Swift function signature of the initializer of the generated struct, which gains a new parameter. Rare, but something to be aware of. Note that when upgrading the generator to a newer version, we reserve the right to add new defaulted properties to generated structs, so such a change is considered non-breaking. For that reason, avoid capturing the function signature of the initializer of any generated struct. > ‡: Adding a new response to an existing operation introduces a new enum case that the adopter needs to handle, so is a breaking change in OpenAPI and Swift. diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md index 10d5ec9c..99617501 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md @@ -6,7 +6,14 @@ Understand the impact of updating the generator package plugin on the generated Swift OpenAPI Generator generates client and server Swift code from an OpenAPI document. The generated code may change if the OpenAPI document is changed or a different version of the generator is used. -This document outlines the API stability goals for the generated code to help you avoid unintentional build errors when updating to a new version of Swift OpenAPI Generator. +This document outlines the API stability goals for the generator to help you avoid unintentional build errors when updating to a new version of Swift OpenAPI Generator. + +The components covered by these rules are: +- the name of the Swift OpenAPI Generator package plugin +- the format of the config file provided to Swift OpenAPI Generator (plugin or CLI tool) +- the Swift OpenAPI Generator CLI tool arguments + +If you upgrade any of the components above to the next non-breaking version, your project should continue to build successfully. Check out how these rules are applied before 1.0 is released, and what a breaking change means for the generated code: . ### API stability for versions >= 1.0.0