From b5acdd0d7cd31bf68e156a29f88d04c2926f501e Mon Sep 17 00:00:00 2001 From: Si Beaumont Date: Mon, 11 Dec 2023 09:12:24 +0000 Subject: [PATCH] Proposal documentation cleanup and consistency (#469) ### Motivation We want to go into 1.0 with the proposal documentation up to date, w.r.t. the version in which the proposal was implemented, and linking to the forums post where they were reviewed. They also have diverged a bit in style. ### Modifications Update the proposal docs for consistent style. I referred again to the style used in the Swift Evolution repo. ### Result Proposal docs consistent and up to date. ### Test Plan None. --- .../Documentation.docc/Proposals/SOAR-0001.md | 12 +++++------- .../Documentation.docc/Proposals/SOAR-0002.md | 10 ++++------ .../Documentation.docc/Proposals/SOAR-0003.md | 12 ++++-------- .../Documentation.docc/Proposals/SOAR-0004.md | 16 ++++------------ .../Documentation.docc/Proposals/SOAR-0005.md | 16 ++++------------ .../Documentation.docc/Proposals/SOAR-0007.md | 18 +++++------------- .../Documentation.docc/Proposals/SOAR-0008.md | 15 +++++---------- .../Documentation.docc/Proposals/SOAR-0009.md | 16 +++++----------- 8 files changed, 36 insertions(+), 79 deletions(-) diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0001.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0001.md index 300903a0..dd2fd3d4 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0001.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0001.md @@ -5,14 +5,12 @@ Improved mapping of OpenAPI identifiers to Swift identifiers. ## Overview - Proposal: SOAR-0001 -- Author(s): [Denil](https://github.com/denil-ct) -- Status: **Accepted, available since 0.2.0.** +- Author(s): [Denil Chungath](https://github.com/denil-ct) +- Status: **Implemented (0.2.0)** - Issue: https://github.com/apple/swift-openapi-generator/issues/21 -- Implementation: - - https://github.com/apple/swift-openapi-generator/pull/89 -- Feature flag: `proposal0001` -- Affected components: - - generator +- Implementation: https://github.com/apple/swift-openapi-generator/pull/89 +- Review: ([review](https://forums.swift.org/t/proposal-ready-for-implementation-soar-0001-improved-openapi-swift-name-mapping/65890)) +- Affected components: generator ### Introduction diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0002.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0002.md index 5c6b9bd8..61488e36 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0002.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0002.md @@ -6,13 +6,11 @@ Improved naming of content types to Swift identifiers. - Proposal: SOAR-0002 - Author(s): [Honza Dvorsky](https://github.com/czechboy0) -- Status: **Accepted, available since 0.2.0.** +- Status: **Implemented (0.2.0)** - Issue: N/A, was part of multiple content type support: [apple/swift-openapi-generator#6](https://github.com/apple/swift-openapi-generator/issues/6) and [apple/swift-openapi-generator#7](https://github.com/apple/swift-openapi-generator/issues/7) -- Implementation: - - [Landed behind a feature flag as part of apple/swift-openapi-generator#146](https://github.com/czechboy0/swift-openapi-generator/blob/4555f8e998b24aa65a462a63828d9195c50dcc23/Sources/_OpenAPIGeneratorCore/Translator/Content/ContentSwiftName.swift#L23-L42) -- Feature flag: `multipleContentTypes` -- Affected components: - - generator +- Implementation: [apple/swift-openapi-generator#146](https://github.com/apple/swift-openapi-generator/pull/146) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0002-improved-naming-of-content-types/66620)) +- Affected components: generator - Versions: - v1 (2023-08-07): First draft - v2 (2023-08-08): Second draft with the following changes: diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0003.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0003.md index c93c9bd8..46cadef3 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0003.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0003.md @@ -6,15 +6,11 @@ Generate a dedicated Accept header enum for each operation. - Proposal: SOAR-0003 - Author(s): [Honza Dvorsky](https://github.com/czechboy0), [Si Beaumont](https://github.com/simonjbeaumont) -- Status: **Accepted, available since 0.2.0.** +- Status: **Implemented (0.2.0)** - Issue: [apple/swift-openapi-generator#160](https://github.com/apple/swift-openapi-generator/issues/160) -- Implementation: - - [apple/swift-openapi-runtime#37](https://github.com/apple/swift-openapi-runtime/pull/37) - - [apple/swift-openapi-generator#185](https://github.com/apple/swift-openapi-generator/pull/185) -- Feature flag: `multipleContentTypes` -- Affected components: - - generator - - runtime +- Implementation: [apple/swift-openapi-runtime#37](https://github.com/apple/swift-openapi-runtime/pull/37), [apple/swift-openapi-generator#185](https://github.com/apple/swift-openapi-generator/pull/185) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0003-type-safe-accept-headers/66785)) +- Affected components: generator, runtime ### Introduction diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md index 6d381d2e..d86c8a30 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0004.md @@ -6,19 +6,11 @@ Represent HTTP request and response bodies as a stream of bytes. - Proposal: SOAR-0004 - Author(s): [Honza Dvorsky](https://github.com/czechboy0) -- Status: **Accepted, available since 0.3.0.** +- Status: **Implemented (0.3.0)** - Issue: [apple/swift-openapi-generator#9](https://github.com/apple/swift-openapi-generator/issues/9) -- Implementation: - - [apple/swift-openapi-generator#245](https://github.com/apple/swift-openapi-generator/pull/245) - - [apple/swift-openapi-runtime#47](https://github.com/apple/swift-openapi-runtime/pull/47) - - [apple/swift-openapi-urlsession#15](https://github.com/apple/swift-openapi-urlsession/pull/15) - - [swift-server/swift-openapi-async-http-client#16](https://github.com/swift-server/swift-openapi-async-http-client/pull/16) -- Feature flag: none, lands as a breaking change to main, gets released as 0.3.0 -- Affected components: - - generator - - runtime - - client transports - - server transports +- Implementation: [apple/swift-openapi-generator#245](https://github.com/apple/swift-openapi-generator/pull/245), [apple/swift-openapi-runtime#47](https://github.com/apple/swift-openapi-runtime/pull/47), [apple/swift-openapi-urlsession#15](https://github.com/apple/swift-openapi-urlsession/pull/15), [swift-server/swift-openapi-async-http-client#16](https://github.com/swift-server/swift-openapi-async-http-client/pull/16) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0004-streaming-request-and-response-bodies/67184)) +- Affected components: generator, runtime, client transports, server transports - Versions: - v1 (2023-09-08): Initial version - v1.1: Make HTTPBody.Iterator.next() mutating diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md index 5f7ce8a3..202025f4 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0005.md @@ -6,19 +6,11 @@ Adopt the new ecosystem-wide Swift HTTP Types package for HTTP currency types in - Proposal: SOAR-0005 - Author(s): [Honza Dvorsky](https://github.com/czechboy0) -- Status: **Accepted, available since 0.3.0.** +- Status: **Implemented (0.3.0)** - Issue: [apple/swift-openapi-generator#101](https://github.com/apple/swift-openapi-generator/issues/101) -- Implementation: - - [apple/swift-openapi-generator#245](https://github.com/apple/swift-openapi-generator/pull/245) - - [apple/swift-openapi-runtime#47](https://github.com/apple/swift-openapi-runtime/pull/47) - - [apple/swift-openapi-urlsession#15](https://github.com/apple/swift-openapi-urlsession/pull/15) - - [swift-server/swift-openapi-async-http-client#16](https://github.com/swift-server/swift-openapi-async-http-client/pull/16) -- Feature flag: none, lands as a breaking change to main, gets released as 0.3.0 -- Affected components: - - generator - - runtime - - client transports - - server transports +- Implementation: [apple/swift-openapi-generator#245](https://github.com/apple/swift-openapi-generator/pull/245), [apple/swift-openapi-runtime#47](https://github.com/apple/swift-openapi-runtime/pull/47), [apple/swift-openapi-urlsession#15](https://github.com/apple/swift-openapi-urlsession/pull/15), [swift-server/swift-openapi-async-http-client#16](https://github.com/swift-server/swift-openapi-async-http-client/pull/16) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0005-adopting-the-swift-http-types-package/67185)) +- Affected components: generator, runtime, client transports, server transports - Versions: - v1 (2023-09-08): Initial version - v1.1: In `ServerTransport` and `ServerMiddleware`, make the response `HTTPBody` optional to preserve the intent of the OpenAPI document author for the transport. diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0007.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0007.md index ff732fff..0eeeba34 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0007.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0007.md @@ -7,21 +7,13 @@ operation outputs. - Proposal: SOAR-0007 - Author(s): [Si Beaumont](https://github.com/simonjbeaumont) -- Status: **Accepted, available since 0.3.0.** +- Status: **Implemented (0.3.0)** - Review period: 2023-09-22 – 2023-09-29 - [Swift Forums post](https://forums.swift.org/t/proposal-soar-0007-shorthand-apis-for-inputs-and-outputs/67444) -- Issue: - - [apple/swift-openapi-generator#22](https://github.com/apple/swift-openapi-generator/issues/22) - - [apple/swift-openapi-generator#104](https://github.com/apple/swift-openapi-generator/issues/104) - - [apple/swift-openapi-generator#105](https://github.com/apple/swift-openapi-generator/issues/105) - - [apple/swift-openapi-generator#145](https://github.com/apple/swift-openapi-generator/issues/145) -- Implementation: - - [apple/swift-openapi-runtime#56](https://github.com/apple/swift-openapi-runtime/pull/56) - - [apple/swift-openapi-generator#308](https://github.com/apple/swift-openapi-generator/pull/308) -- Feature flag: none -- Affected components: - - generator - - runtime +- Issue: [apple/swift-openapi-generator#22](https://github.com/apple/swift-openapi-generator/issues/22), [apple/swift-openapi-generator#104](https://github.com/apple/swift-openapi-generator/issues/104), [apple/swift-openapi-generator#105](https://github.com/apple/swift-openapi-generator/issues/105), [apple/swift-openapi-generator#145](https://github.com/apple/swift-openapi-generator/issues/145) +- Implementation: [apple/swift-openapi-runtime#56](https://github.com/apple/swift-openapi-runtime/pull/56), [apple/swift-openapi-generator#308](https://github.com/apple/swift-openapi-generator/pull/308) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0007-shorthand-apis-for-inputs-and-outputs/67444)) +- Affected components: generator, runtime - Related links: - [Project scope and goals](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/project-scope-and-goals) - Versions: diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md index e9ececf6..ea3a1d95 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0008.md @@ -6,16 +6,11 @@ Filtering the OpenAPI document for just the required parts prior to generating. - Proposal: SOAR-0008 - Author(s): [Si Beaumont](https://github.com/simonjbeaumont) -- Status: **Accepted, available since 0.3.1.** - - Review period: 2023-09-28 – 2023-10-05 - - [Swift Forums post](https://forums.swift.org/t/proposal-soar-0008-openapi-document-filtering/67574) -- Issue: - - [apple/swift-openapi-generator#285](https://github.com/apple/swift-openapi-generator/issues/285) -- Implementation: - - [apple/swift-openapi-generator#319](https://github.com/apple/swift-openapi-generator/pull/319) -- Feature flag: n/a -- Affected components: - - generator +- Status: **Implemented (0.3.0)** +- Issue: [apple/swift-openapi-generator#285](https://github.com/apple/swift-openapi-generator/issues/285) +- Implementation: [apple/swift-openapi-generator#319](https://github.com/apple/swift-openapi-generator/pull/319) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0008-openapi-document-filtering/67574)) +- Affected components: generator - Related links: - [Project scope and goals](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/project-scope-and-goals) - Versions: diff --git a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0009.md b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0009.md index 4481f639..ccb7313f 100644 --- a/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0009.md +++ b/Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0009.md @@ -6,18 +6,12 @@ Provide a type-safe streaming API to produce and consume multipart bodies. - Proposal: SOAR-0009 - Author(s): [Honza Dvorsky](https://github.com/czechboy0) -- Status: **Accepted, available since 1.0.0-alpha.1** - - Review period: 2023-11-08 – 2023-11-15 - - [Swift Forums post](https://forums.swift.org/t/proposal-soar-0009-type-safe-streaming-multipart-support/68331) +- Status: **Implemented (1.0.0)** - Issue: [apple/swift-openapi-generator#36](https://github.com/apple/swift-openapi-generator/issues/36) -- Implementation: - - [apple/swift-openapi-runtime#69](https://github.com/apple/swift-openapi-runtime/pull/69) - - [apple/swift-openapi-generator#366](https://github.com/apple/swift-openapi-generator/pull/366) -- Feature flag: none -- Affected components: - - generator - - runtime -- Links: +- Implementation: [apple/swift-openapi-runtime#69](https://github.com/apple/swift-openapi-runtime/pull/69), [apple/swift-openapi-generator#366](https://github.com/apple/swift-openapi-generator/pull/366) +- Review: ([review](https://forums.swift.org/t/proposal-soar-0009-type-safe-streaming-multipart-support/68331)) +- Affected components: generator, runtime +- Related links: - [OpenAPI 3.0.3 specification][openapi303] - [OpenAPI 3.1.0 specification][openapi310] - [Swagger.io documentation on multipart support in OpenAPI 3.x][swaggerio-multipart]