Add OpenAPI documents for the toolchains and Swift evolution APIs

[czechboy0]

Motivation:

Fixes #832.

Swift.org has an undocumented swift.org API that's used by swiftly and other tools to fetch releases, and a download.swift.org API that's used by the Swift Evolution web dashboard.

Modifications:

• Added an OpenAPI document describing the current v1 of the swift.org and download.swift.org APIs.
• Added a test project that generates a Swift client and validates that all the content successfully parses, i.e. that the OpenAPI document is in-sync with the returned data.
• Added a footer item called "API" that points to the docs (see screenshot below).
• Added a Swagger UI-based preview that has a picked between the two OpenAPI documents (see screenshots below).

Result:

Tools can use the OpenAPI document to generate a client in any language, and more easily keep up with future API evolution.

[0xTim]

Is there a way we can autogenerate this? Otherwise keeping this up to date with new APIs is going to get out of date pretty quick

[czechboy0]

Autogenerate from where? This will be the source of truth, and any generation would happen the other way - from this document, generating clients, and if the API ever becomes a dynamic server (it's static files right now), also generate the server stubs.

This PR contains a CLI that verifies the compliance of the static files with the OpenAPI doc, so keeping things in sync should be easy.

We want changes to be done deliberately, but recently swiftly was broken because of a miscommunication between the two parties. More details on how spec-driven helps avoid similar issues, and allows us to discuss the API without getting bogged down by implementation: https://swiftpackageindex.com/apple/swift-openapi-generator/1.4.0/documentation/swift-openapi-generator/practicing-spec-driven-api-development

[0xTim]

So to start I want to be clear that the goal of having the API documented by the an OpenAPI spec is a great one and we should do it.

My question is more technical. Currently the API is generated via Jekyll from JSON templates. The YAML file is handwritten and any new APIs added (we're currently adding one for the SSWG incubated packages) would need to be manually added to the YAML. This is going to get out of sync pretty quickly.

What options do we have to either generate the YAML file from the information that Jekyll has or take the YAML file and generate the API somehow. Currently since a lot of the API is generated from data files we need to go through Jekyll currently and I don't think we have the same options of failing the build if they don't exist like we do in Swift

[czechboy0]

Right, so if we accept that the OpenAPI doc is the source of truth, and the JSON files are the "server implementation", then we should find a way to verify that the implementation follows the specification whenever it changes. It's not required, but it's a good practice.

In my PR, this is done with the sample project for the install API, and we don't have any automated verification for the evolution API (as the evolution JSON files aren't checked in).

I'll add that that's still better than status quo, but I agree this should be firmed up in subsequent PRs. I'm happy to do some of that work if people have ideas, but I don't think it needs to block the initial API docs.

[timsneath]

This feels like a perfect job for Pkl (https://pkl-lang.org), which is Apple's strongly-typed tool for generating static configuration files...

[czechboy0]

Sure, as a future optimization we could write the OpenAPI doc in pkl and render it into YAML as a build step. But YAML is the published format that tools consume.

[czechboy0]

FYI, I also added an OpenAPI document for the download.swift.org API that vends Swift Evolution metadata.

[czechboy0]

Now, as I was documenting the existing API, I have ideas of what an eventual v2 API could look like (for example, unify them under the same hostname and OpenAPI document). However, I think it's important that we're documenting what we have today, as a starting point for any discussion for changing the API in the future.

In other words, documenting this API does not imply a higher commitment to this API than when it was undocumented - we only make explicit what was already there, to allow for an easier collaboration and consumption of the API. We want to avoid the (sadly) common approach of "we don't want to document this API because we don't want to commit to it" (documented vs undocumented and committed vs uncommitted are completely orthogonal) - thus my disclaimer above 🙂 Documenting these APIs only moves us in the right direction without taking anything away.

[czechboy0]

I'm happy to review future changes to the OpenAPI documents, but that'd require me to receive write access - I'll leave that up to the SWWG to decide whether that's valuable for me to have or not.