[Docs] Clarify that number/names of generated files are not API + other polish (#450)

### Motivation

The number and names of generated files should not be considered APIs,
to allow us to introduce future optimization, such as
#253.

### Modifications

Clarified in the docs, also removed some pre-1.0 stuff, plus some other
minor fixups.

### Result

Clearer docs.

### Test Plan

Previewed locally.

Author: czechboy0

README.md

@@ -35,9 +35,7 @@ Choose one of the transports listed below, or create your own by adopting the `C
 
 | Generator versions | Supported OpenAPI versions | Minimum Swift version |
 | -------- | ------- | ----- |
-| `0.1.0` ... `0.1.11` | 3.0 | 5.8 |
-| `0.1.12` ... `0.3.5` | 3.0, 3.1 | 5.8 |
-| `1.0.0-alpha.1` ... `main` | 3.0, 3.1 | 5.9 |
+| `1.0.0` ... `main` | 3.0, 3.1 | 5.9 |
 
 ### Supported platforms and minimum versions
 

Sources/swift-openapi-generator/Documentation.docc/Articles/API-stability-of-the-generator.md

@@ -8,27 +8,25 @@ Swift OpenAPI Generator generates client and server Swift code from an OpenAPI d
 
 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
+Swift OpenAPI Generator follows [Semantic Versioning 2.0.0][0] for the following, which are considered part of its API:
 
-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: <doc:API-stability-of-generated-code>.
+- 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, options, and flags.
 
-### API stability for versions >= 1.0.0
+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, and what a breaking change means for the generated code: <doc:API-stability-of-generated-code>.
 
-After the project reaches 1.0.0, we will follow [Semantic Versioning 2.0.0][0].
+### Implementation details
 
-### API stability for versions 0.y.z
+In contrast to the guarantees provided for the API of Swift OpenAPI Generator, the following list of behaviors are _not_ considered API, and can change without prior warning:
 
-Swift OpenAPI Generator is being developed as an open source project. In order to accommodate feedback from the community, it does not yet have a 1.0.0 release. Until it does, we reserve the right to change the API between _minor_ versions (for example, between `0.2.0` and `0.3.0`), as described in the Semantic Version Specification[[1]][[2]].
-
-> Tip: To avoid unexpected build issues, use `.upToNextMinor(from: "0.y.z")` in your `Package.swift` when declaring a dependency on Swift OpenAPI Generator packages (including the runtime and transport libraries).
+- The number and names of files generated by the Swift OpenAPI Generator CLI and plugins.
+- The SPI provided by the OpenAPIRuntime library used by generated code (marked with `@_spi(Generated)`).
+- The business logic of the generated code, any code that isn't part of the API of the generated code.
+- The diagnostics emitted by the generator, both their severity and printed description.
 
 ## See Also
 
 - <doc:API-stability-of-generated-code>
 
 [0]: https://semver.org
-[1]: https://semver.org/#spec-item-4
-[2]: https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase

Sources/swift-openapi-generator/Documentation.docc/Articles/Contributing-to-Swift-OpenAPI-Generator.md

@@ -72,4 +72,4 @@ Let's walk through the steps to implement a missing OpenAPI feature that require
 
 11. All done! Thank you for your contribution! 🙏
 
-[0]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-10
+[0]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-10

Sources/swift-openapi-generator/Documentation.docc/Articles/Starting-with-an-example-project.md

@@ -1,10 +1,10 @@
-# Starting with an example project
+# Checking out an example project
 
-Duplicate a working example to start your project.
+Check out a working example to learn how packages using Swift OpenAPI Generator can be structured and integrated with the ecosystem.
 
 ## Overview
 
-All the examples are self-contained, so you can copy the package directory of your chosen example and use it as a starter template for your project.
+All the examples are self-contained, so you can copy the package directory of your chosen example and run it independently.
 
 ### Getting started
 

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

@@ -16,7 +16,7 @@ Supported features are always provided on _both_ client and server.
 
 For the checked serialization formats below, the generator emits types conforming to `Codable`, structured based on the provided JSON Schema.
 
-For any other formats, the payload is provided as raw bytes, leaving it up to the adopter to decode as needed.
+For any other formats, the payload is provided as raw bytes (using the `HTTPBody` streaming body type), leaving it up to the adopter to decode as needed.
 
 - [x] JSON
     - when content type is `application/json` or ends with `+json`

Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md

@@ -16,7 +16,7 @@ The code is generated at build-time, so it's always in sync with the OpenAPI doc
 
 ### Getting started
 
-> Tip: In a rush? Duplicate a working example to start your project: <doc:Starting-with-an-example-project>.
+> Tip: In a rush? Check out a working example: <doc:Starting-with-an-example-project>.
 
 Alternatively, to integrate Swift OpenAPI Generator into your existing project, or to create a new one, follow one of our _getting started_ guides:
 - <doc:ClientXcode>
@@ -50,9 +50,7 @@ Choose one of the transports listed below, or create your own by adopting the `C
 
 | Generator versions | Supported OpenAPI versions | Minimum Swift version |
 | -------- | ------- | ----- |
-| `0.1.0` ... `0.1.11` | 3.0 | 5.8 |
-| `0.1.12` ... `0.3.5` | 3.0, 3.1 | 5.8 |
-| `1.0.0-alpha.1` ... `main` | 3.0, 3.1 | 5.9 |
+| `1.0.0` ... `main` | 3.0, 3.1 | 5.9 |
 
 See also <doc:Supported-OpenAPI-features>.