[Docs] Add the Examples index to the docc docs (#468)

### Motivation

Copy the Examples/README.md contents to the docc docs as well, as it's a
great starting point.

### Modifications

Some more polish + copied the contents (and updated links) for the
examples.

### Result

Easier to get started with examples when landing in the docc docs.

### Test Plan

Tested that all the links work.

Author: czechboy0

Examples/README.md

@@ -1,62 +1,69 @@
 # Examples of using Swift OpenAPI Generator
 
-This directory contains examples of how to use Swift OpenAPI Generator and
-integrate with other packages in the ecosystem.
+This directory contains examples of how to use and
+integrate Swift OpenAPI Generator with other packages in the ecosystem.
 
-> **Disclaimer:** Many of these examples have been deliberately simplified and are
-> intended for illustrative purposes only.
+> Important: Many of these examples have been deliberately simplified and are intended for illustrative purposes only.
 
-## Getting started
+All the examples can be found in the [Examples](https://github.com/apple/swift-openapi-generator/tree/main/Examples) directory of the [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator) repository.
 
-Each of the following packages shows an end-to-end working example with the given transport.
+To run an example locally, for example [hello-world-urlsession-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-urlsession-client-example), clone the Swift OpenAPI Generator repository, and run the example, as shown below:
 
+```console
+% git clone https://github.com/apple/swift-openapi-generator
+% cd swift-openapi-generator/Examples
+% swift run --package-path hello-world-urlsession-client-example
+```
 
+## Getting started
+
+Each of the following packages shows an end-to-end working example with the given transport.
 
-- [hello-world-async-http-client-example](./hello-world-async-http-client-example) - A CLI client using the AsyncHTTPClient library.
-- [hello-world-hummingbird-server-example](./hello-world-hummingbird-server-example) - A CLI server using the Hummingbird web framework.
-- [hello-world-urlsession-client-example](./hello-world-urlsession-client-example) - A CLI client using the URLSession HTTP client library.
-- [hello-world-vapor-server-example](./hello-world-vapor-server-example) - A CLI client using the Vapor web framework.
+- [hello-world-urlsession-client-example](./hello-world-urlsession-client-example) - A CLI client using the [URLSession](https://developer.apple.com/documentation/foundation/urlsession) API.
+- [hello-world-async-http-client-example](./hello-world-async-http-client-example) - A CLI client using the [AsyncHTTPClient](https://github.com/swift-server/async-http-client) library.
+- [hello-world-vapor-server-example](./hello-world-vapor-server-example) - A CLI server using the [Vapor](https://github.com/vapor/vapor) web framework.
+- [hello-world-hummingbird-server-example](./hello-world-hummingbird-server-example) - A CLI server using the [Hummingbird](https://github.com/hummingbird-project/hummingbird) web framework.
+- [HelloWorldiOSClientAppExample](./HelloWorldiOSClientAppExample) - An iOS client SwiftUI app with a mock server for unit and UI tests.
 - [curated-client-library-example](./curated-client-library-example) - A library that hides the generated API and exports a hand-written interface, allowing decoupled versioning.
-- [HelloWorldiOSClientAppExample](./HelloWorldiOSClientAppExample) - An iOS client SwiftUI app with mock server for unit and UI tests.
 
 ## Various content types
 
 The following packages show working with various content types, such as JSON, URL-encoded request bodies, plain text, raw bytes, and multipart bodies.
 
-- [various-content-types-client-example](./various-content-types-client-example) - A client showing how to request and handle the various content types.
+- [various-content-types-client-example](./various-content-types-client-example) - A client showing how to provide and handle the various content types.
 - [various-content-types-server-example](./various-content-types-server-example) - A server showing how to handle and provide the various content types.
 
 ## Integrations
 
-- [swagger-ui-endpoint-example](./swagger-ui-endpoint-example) - A server with endpoints its raw OpenAPI document and Swagger UI.
-- [postgres-database-example](./postgres-database-example) - A server using a Postgres database for persistent state.
-- [command-line-client-example](./command-line-client-example) - A client with a rich CLI using Swift Argument Parser.
+- [swagger-ui-endpoint-example](./swagger-ui-endpoint-example) - A server with endpoints for its raw OpenAPI document and interactive documentation using [Swagger UI](https://github.com/swagger-api/swagger-ui).
+- [postgres-database-example](./postgres-database-example) - A server using a [Postgres](https://www.postgresql.org) database for persistent state.
+- [command-line-client-example](./command-line-client-example) - A client with a rich command-line interface using [Swift Argument Parser](https://github.com/apple/swift-argument-parser).
 
 ## Middleware
 
-- [logging-middleware-oslog-example](./logging-middleware-oslog-example) - A middleware that logs requests and responses using OSLog.
-- [logging-middleware-swift-log-example](./logging-middleware-swift-log-example) - A middleware that logs requests and responses using Swift Log.
-- [metrics-middleware-example](./metrics-middleware-example) - A middleware that collects metrics using Swift Metrics.
-- [tracing-middleware-example](./tracing-middleware-example) - A middleware that collects traces using Swift Distributed Tracing.
-- [retrying-middleware-example](./retrying-middleware-example) - A middleware that retries failed requests.
-- [auth-client-middleware-example](./auth-client-middleware-example) - An middleware that injects a token header.
-- [auth-server-middleware-example](./auth-server-middleware-example) - An middleware that inspects a token header.
+- [logging-middleware-oslog-example](./logging-middleware-oslog-example) - A middleware that logs requests and responses using [OSLog](https://developer.apple.com/documentation/os/oslog) (only available on Apple platforms, such as macOS, iOS, and more).
+- [logging-middleware-swift-log-example](./logging-middleware-swift-log-example) - A middleware that logs requests and responses using [SwiftLog](https://github.com/apple/swift-log).
+- [metrics-middleware-example](./metrics-middleware-example) - A middleware that collects metrics using [SwiftMetrics](https://github.com/apple/swift-metrics).
+- [tracing-middleware-example](./tracing-middleware-example) - A middleware that emits traces using [Swift Distributed Tracing](https://github.com/apple/swift-distributed-tracing).
+- [retrying-middleware-example](./retrying-middleware-example) - A middleware that retries some failed requests.
+- [auth-client-middleware-example](./auth-client-middleware-example) - A middleware that injects a token header.
+- [auth-server-middleware-example](./auth-server-middleware-example) - A middleware that inspects a token header.
 
 ## Ahead-of-time (manual) code generation
 
-The recommended way to use Swift OpenAPI generator is by integrating the _build plugin_, which all of the examples above use. The build plugin generates Swift code from your OpenAPI document at build time, and you don't check in the generated code into git. 
+The recommended way to use Swift OpenAPI generator is by integrating the _build plugin_, which all of the examples above use. The build plugin generates Swift code from your OpenAPI document at build time, and you don't check in the generated code into your git repository. 
 
 However, if you cannot use the build plugin, for example because you must check in your generated code, use the _command plugin_, which you trigger manually either in Xcode or on the command line. See the following example for this workflow:
 
-- [manual-generation-package-plugin-example](./manual-generation-package-plugin-example) - A client using the Swift package plugin for manual code generation.
+- [manual-generation-package-plugin-example](./manual-generation-package-plugin-example) - A client using the Swift package command plugin for manual code generation.
 
-If you can't even use the command plugin, for example because your package is not allowed to depend on swift-openapi-generator directly, you can invoke the generator CLI manually from a Makefile. See the following example for this workflow:
+If you can't even use the command plugin, for example because your package is not allowed to depend on Swift OpenAPI Generator, you can invoke the generator CLI manually from a Makefile. See the following example for this workflow:
 
 - [manual-generation-generator-cli-example](./manual-generation-generator-cli-example) - A client using the `swift-openapi-generator` CLI for manual code generation.
 
 ## Deprecated
 
 The following examples will be removed before 1.0.0 is released and is preserved for backwards compatibility with currently published tutorials that point to it.
 
-- [`GreetingService`](./GreetingService) - a Vapor-based CLI server, use `HelloWorldVaporServer` instead
-- [`GreetingServiceClient`](./GreetingServiceClient) - a URLSession-based CLI client, use `HelloWorldURLSessionClient` instead
+- [`GreetingService`](./GreetingService) - A Vapor-based CLI server, use [`hello-world-vapor-server-example`](./hello-world-vapor-server-example) instead.
+- [`GreetingServiceClient`](./GreetingServiceClient) - A URLSession-based CLI client, use [`hello-world-urlsession-client-example`](./hello-world-urlsession-client-example) instead.

Examples/logging-middleware-oslog-example/Sources/HelloWorldURLSessionClient/HelloWorldURLSessionClient.swift

@@ -26,7 +26,7 @@ import LoggingMiddleware
         let response = try await client.getGreeting()
         print(try response.ok.body.json.message)
         #else  //canImport(Darwin)
-        print("This example uses OSLog, so is only supported on Darwin platforms")
+        print("This example uses OSLog, so is only supported on Apple platforms")
         exit(EXIT_FAILURE)
         #endif  //canImport(Darwin)
     }

Sources/swift-openapi-generator/Documentation.docc/Articles/Checking-out-an-example-project.md

@@ -0,0 +1,72 @@
+# Checking out an example project
+
+Check out a working example to learn how packages using Swift OpenAPI Generator can be structured and integrated with the ecosystem.
+
+## Overview
+
+The following examples show how to use and integrate Swift OpenAPI Generator with other packages in the ecosystem.
+
+> Important: Many of these examples have been deliberately simplified and are intended for illustrative purposes only.
+
+All the examples can be found in the [Examples](https://github.com/apple/swift-openapi-generator/tree/main/Examples) directory of the [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator) repository.
+
+To run an example locally, for example [hello-world-urlsession-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-urlsession-client-example), clone the Swift OpenAPI Generator repository, and run the example, as shown below:
+
+```console
+% git clone https://github.com/apple/swift-openapi-generator
+% cd swift-openapi-generator/Examples
+% swift run --package-path hello-world-urlsession-client-example
+```
+
+## Getting started
+
+Each of the following packages shows an end-to-end working example with the given transport.
+
+- [hello-world-urlsession-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-urlsession-client-example) - A CLI client using the [URLSession](https://developer.apple.com/documentation/foundation/urlsession) API.
+- [hello-world-async-http-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-async-http-client-example) - A CLI client using the [AsyncHTTPClient](https://github.com/swift-server/async-http-client) library.
+- [hello-world-vapor-server-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-vapor-server-example) - A CLI server using the [Vapor](https://github.com/vapor/vapor) web framework.
+- [hello-world-hummingbird-server-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-hummingbird-server-example) - A CLI server using the [Hummingbird](https://github.com/hummingbird-project/hummingbird) web framework.
+- [HelloWorldiOSClientAppExample](https://github.com/apple/swift-openapi-generator/tree/main/Examples/HelloWorldiOSClientAppExample) - An iOS client SwiftUI app with a mock server for unit and UI tests.
+- [curated-client-library-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/curated-client-library-example) - A library that hides the generated API and exports a hand-written interface, allowing decoupled versioning.
+
+## Various content types
+
+The following packages show working with various content types, such as JSON, URL-encoded request bodies, plain text, raw bytes, and multipart bodies.
+
+- [various-content-types-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/various-content-types-client-example) - A client showing how to provide and handle the various content types.
+- [various-content-types-server-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/various-content-types-server-example) - A server showing how to handle and provide the various content types.
+
+## Integrations
+
+- [swagger-ui-endpoint-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/swagger-ui-endpoint-example) - A server with endpoints for its raw OpenAPI document and interactive documentation using [Swagger UI](https://github.com/swagger-api/swagger-ui).
+- [postgres-database-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/postgres-database-example) - A server using a [Postgres](https://www.postgresql.org) database for persistent state.
+- [command-line-client-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/command-line-client-example) - A client with a rich command-line interface using [Swift Argument Parser](https://github.com/apple/swift-argument-parser).
+
+## Middleware
+
+- [logging-middleware-oslog-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/logging-middleware-oslog-example) - A middleware that logs requests and responses using [OSLog](https://developer.apple.com/documentation/os/oslog) (only available on Apple platforms, such as macOS, iOS, and more).
+- [logging-middleware-swift-log-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/logging-middleware-swift-log-example) - A middleware that logs requests and responses using [SwiftLog](https://github.com/apple/swift-log).
+- [metrics-middleware-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/metrics-middleware-example) - A middleware that collects metrics using [SwiftMetrics](https://github.com/apple/swift-metrics).
+- [tracing-middleware-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/tracing-middleware-example) - A middleware that emits traces using [Swift Distributed Tracing](https://github.com/apple/swift-distributed-tracing).
+- [retrying-middleware-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/retrying-middleware-example) - A middleware that retries some failed requests.
+- [auth-client-middleware-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/auth-client-middleware-example) - A middleware that injects a token header.
+- [auth-server-middleware-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/auth-server-middleware-example) - A middleware that inspects a token header.
+
+## Ahead-of-time (manual) code generation
+
+The recommended way to use Swift OpenAPI generator is by integrating the _build plugin_, which all of the examples above use. The build plugin generates Swift code from your OpenAPI document at build time, and you don't check in the generated code into your git repository. 
+
+However, if you cannot use the build plugin, for example because you must check in your generated code, use the _command plugin_, which you trigger manually either in Xcode or on the command line. See the following example for this workflow:
+
+- [manual-generation-package-plugin-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/manual-generation-package-plugin-example) - A client using the Swift package command plugin for manual code generation.
+
+If you can't even use the command plugin, for example because your package is not allowed to depend on Swift OpenAPI Generator, you can invoke the generator CLI manually from a Makefile. See the following example for this workflow:
+
+- [manual-generation-generator-cli-example](https://github.com/apple/swift-openapi-generator/tree/main/Examples/manual-generation-generator-cli-example) - A client using the `swift-openapi-generator` CLI for manual code generation.
+
+## Deprecated
+
+The following examples will be removed before 1.0.0 is released and is preserved for backwards compatibility with currently published tutorials that point to it.
+
+- [`GreetingService`](https://github.com/apple/swift-openapi-generator/tree/main/Examples/GreetingService) - A Vapor-based CLI server, use [`hello-world-vapor-server-example`](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-vapor-server-example) instead.
+- [`GreetingServiceClient`](https://github.com/apple/swift-openapi-generator/tree/main/Examples/GreetingServiceClient) - A URLSession-based CLI client, use [`hello-world-urlsession-client-example`](https://github.com/apple/swift-openapi-generator/tree/main/Examples/hello-world-urlsession-client-example) instead.

Sources/swift-openapi-generator/Documentation.docc/Articles/Starting-with-an-example-project.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? Check out a working example: <doc:Starting-with-an-example-project>.
+> Tip: In a rush? Get started quickly by <doc:Checking-out-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>
@@ -68,7 +68,7 @@ The generated code, runtime library, and transports are supported on more platfo
 ## Topics
 
 ### Essentials
-- <doc:Starting-with-an-example-project>
+- <doc:Checking-out-an-example-project>
 - <doc:ClientSwiftPM>
 - <doc:ClientXcode>
 - <doc:ServerSwiftPM>