[Docs] Add a tutorial for adding /openapi and /openapi.yaml to a server (#429)

czechboy0 · simonjbeaumont · web-flow · commit 12cade2665df · 2023-12-07T05:45:24.000-08:00
### Motivation

In addition to the example project, also document how to add the
/openapi and /openapi.yaml endpoints to an existing server.

### Modifications

Added the tutorial.

### Result

Developers can vend their OpenAPI documents and rendered docs in a
consistent way.

### Test Plan

Walked through it manually to verify that the steps lead to a working
example.

---------

Co-authored-by: Si Beaumont &lt;simonjbeaumont@gmail.com&gt;
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md b/Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md
@@ -77,6 +77,7 @@ The generated code, runtime library, and transports are supported on more platfo
 
 ### OpenAPI
 - <doc:ExploreOpenAPI>
+- <doc:Adding-openapi-and-swagger-ui-endpoints>
 - <doc:Practicing-spec-driven-API-development>
 - <doc:Useful-OpenAPI-patterns>
 - <doc:Supported-OpenAPI-features>
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/Adding-openapi-and-swagger-ui-endpoints.tutorial b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/Adding-openapi-and-swagger-ui-endpoints.tutorial
@@ -0,0 +1,74 @@
+@Tutorial(time: 5) {
+    @Intro(title: "Adding OpenAPI and Swagger UI endpoints") {
+        One of the most popular ways to share your OpenAPI document with your users is to host it alongside your API server itself.
+        
+        Typically this is at `/openapi.yaml` or similar, which serves a plain-text OpenAPI document for consumpion by clients.
+        
+        Additionally, you can host an HTML page that renders the OpenAPI document as interactive documentation that you can use from the browser, for example using [swagger-ui](https://github.com/swagger-api/swagger-ui).
+        
+        In this tutorial we'll add both endpoints to our Vapor server.
+        
+        > Tip: The [OpenAPIEndpointsServer example package](https://github.com/apple/swift-openapi-generator/tree/main/Examples/OpenAPIEndpointsServer) contains the configured Vapor server, in case you want to see the result of this tutorial.
+    }
+
+    @Section(title: "Add an /openapi.yaml endpoint") {
+        
+        We'll start with the server in its state following <doc:ServerSwiftPM> (before the `/emoji` endpoint is added) and we'll add an `/openapi.yaml` endpoint that serves the OpenAPI document as a static resource.
+
+        @Steps {
+            @Step {
+                Create a `Public/` directory for serving static content.
+                
+                @Code(name: "console", file: server-openapi-endpoints.console.0.txt, reset: true)
+            }
+            @Step {
+                Move `openapi.yaml` from `Sources/` and create a symlink to it back in the `Sources/` directory.
+                
+                @Code(name: "console", file: server-openapi-endpoints.console.1.txt, previousFile: server-openapi-endpoints.console.0.txt)
+            }
+            @Step {
+                In `main.swift`, Add a Vapor middleware that serves the contents of the `Public/` directory.
+                
+                @Code(name: "main.swift", file: server-openapi-endpoints.main.1.swift, previousFile: server-openapi-endpoints.main.0.swift)
+            }
+            @Step {
+                From the `Product` menu, select `Scheme > Edit Scheme...`. With `Run` selected in the sidebar, select the `Options` tab and check the box labeled `Use custom working directory` and use the path containing Package.swift for this package.
+                
+                This step is necessary because the Vapor middleware serves files relative to the current working directory for the running server process.
+            }
+            @Step {
+                Test this enpoint in your browser, or using curl.
+                
+                @Code(name: "console", file: server-openapi-endpoints.console.2.txt, previousFile: server-openapi-endpoints.console.1.txt)
+            }
+        }
+    }
+    @Section(title: "Add a Swagger UI endpoint") {
+        Now we'll add a static `openapi.html` page that serves Swagger UI and add a redirect to this page from `/` for discoverability.
+        
+        @Steps {
+            @Step {
+                Create the file `Public/openapi.html` with the swagger-ui JavaScript.
+                
+                By placing it in the public directory, it is already reachable at `/openapi.html`.
+                
+                @Code(name: "openapi.html", file: server-openapi-endpoints.openapi.html, reset: true)
+            }
+            @Step {
+                Add a redirect for `/openapi` to `openapi.html`, which serves the rendered documentation.
+                
+                @Code(name: "main.swift", file: server-openapi-endpoints.main.2.swift, previousFile: server-openapi-endpoints.main.1.swift)
+            }
+            @Step {
+                Add a relative server URL to the OpenAPI document.
+                
+                This allows you to use the rendered documentation to make requests to the instance serving the OpenAPI document itself.
+                
+                @Code(name: "main.swift", file: server-openapi-endpoints.openapi.1.yaml, previousFile: server-openapi-endpoints.openapi.0.yaml)
+            }
+            @Step {
+                Visit `http://localhost:8080/openapi` in your browser which should show the rendered documentation for the OpenAPI document.
+            }
+        }
+    }
+}
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/ServerSwiftPM.tutorial b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/ServerSwiftPM.tutorial
@@ -60,7 +60,7 @@
                 @Code(name: "Package.swift", file: server.Package.2.swift)
             }
             @Step {
-                Now we can update our target to make use of the Swift OpenAPI Generator plugin and add the runtime dependencies for our target.
+                Now we can update our target to make use of the Swift OpenAPI Generator plugin.
                 @Code(name: "Package.swift", file: server.Package.3.swift)
             }
             @Step {
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/Swift OpenAPI Generator.tutorial b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/Swift OpenAPI Generator.tutorial
@@ -30,5 +30,6 @@
         @TutorialReference(tutorial: "doc:ServerSwiftPM")
         @TutorialReference(tutorial: "doc:ClientSwiftPM")
         @TutorialReference(tutorial: "doc:ClientXcode")
+        @TutorialReference(tutorial: "doc:Adding-openapi-and-swagger-ui-endpoints")
     }
 }
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.0.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.0.swift
@@ -5,8 +5,7 @@ let package = Package(
     name: "GreetingServiceClient",
     targets: [
         .executableTarget(
-            name: "GreetingServiceClient",
-            path: "Sources"
+            name: "GreetingServiceClient"
         )
     ]
 )
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.1.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.1.swift
@@ -11,8 +11,7 @@ let package = Package(
     ],
     targets: [
         .executableTarget(
-            name: "GreetingServiceClient",
-            path: "Sources"
+            name: "GreetingServiceClient"
         )
     ]
 )
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.2.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.2.swift
@@ -16,8 +16,7 @@ let package = Package(
     ],
     targets: [
         .executableTarget(
-            name: "GreetingServiceClient",
-            path: "Sources"
+            name: "GreetingServiceClient"
         )
     ]
 )
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.3.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.3.swift
@@ -17,7 +17,6 @@ let package = Package(
     targets: [
         .executableTarget(
             name: "GreetingServiceClient",
-            path: "Sources",
             plugins: [
                 .plugin(
                     name: "OpenAPIGenerator",
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.4.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.4.swift
@@ -27,7 +27,6 @@ let package = Package(
                     package: "swift-openapi-urlsession"
                 ),
             ],
-            path: "Sources",
             plugins: [
                 .plugin(
                     name: "OpenAPIGenerator",
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.5.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/client.Package.5.swift
@@ -27,7 +27,6 @@ let package = Package(
                     package: "swift-openapi-urlsession"
                 ),
             ],
-            path: "Sources",
             plugins: [
                 .plugin(
                     name: "OpenAPIGenerator",
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.0.txt b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.0.txt
@@ -0,0 +1 @@
+% mkdir Public
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.1.txt b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.1.txt
@@ -0,0 +1,5 @@
+% mkdir Public
+
+% mv Sources/openapi.yaml Public/
+
+% ln -s ../Public/openapi.yaml Sources/openapi.yaml
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.2.txt b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.console.2.txt
@@ -0,0 +1,21 @@
+% mkdir Public
+
+% mv Sources/openapi.yaml Public/
+
+% ln -s ../Public/openapi.yaml Sources/openapi.yaml
+
+% curl "localhost:8080/openapi.yaml"
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+paths:
+  /greet:
+    get:
+      operationId: getGreeting
+      parameters:
+        - name: name
+---[SNIP]---
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.0.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.0.swift
@@ -0,0 +1,32 @@
+import Foundation
+import Vapor
+import OpenAPIRuntime
+import OpenAPIVapor
+
+// Define a type that conforms to the generated protocol.
+struct GreetingServiceAPIImpl: APIProtocol {
+    func getGreeting(
+        _ input: Operations.getGreeting.Input
+    ) async throws -> Operations.getGreeting.Output {
+        let name = input.query.name ?? "Stranger"
+        let greeting = Components.Schemas.Greeting(message: "Hello, \(name)!")
+        return .ok(.init(body: .json(greeting)))
+    }
+}
+
+// Create your Vapor application.
+let app = Vapor.Application()
+
+// Create a VaporTransport using your application.
+let transport = VaporTransport(routesBuilder: app)
+
+// Create an instance of your handler type that conforms the generated protocol
+// defininig your service API.
+let handler = GreetingServiceAPIImpl()
+
+// Call the generated function on your implementation to add its request
+// handlers to the app.
+try handler.registerHandlers(on: transport, serverURL: Servers.server1())
+
+// Start the app as you would normally.
+try app.run()
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.1.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.1.swift
@@ -0,0 +1,35 @@
+import Foundation
+import Vapor
+import OpenAPIRuntime
+import OpenAPIVapor
+
+// Define a type that conforms to the generated protocol.
+struct GreetingServiceAPIImpl: APIProtocol {
+    func getGreeting(
+        _ input: Operations.getGreeting.Input
+    ) async throws -> Operations.getGreeting.Output {
+        let name = input.query.name ?? "Stranger"
+        let greeting = Components.Schemas.Greeting(message: "Hello, \(name)!")
+        return .ok(.init(body: .json(greeting)))
+    }
+}
+
+// Create your Vapor application.
+let app = Vapor.Application()
+
+// Create a VaporTransport using your application.
+let transport = VaporTransport(routesBuilder: app)
+
+// Create an instance of your handler type that conforms the generated protocol
+// defininig your service API.
+let handler = GreetingServiceAPIImpl()
+
+// Call the generated function on your implementation to add its request
+// handlers to the app.
+try handler.registerHandlers(on: transport, serverURL: Servers.server1())
+
+// Add Vapor middleware to serve the contents of the Public/ directory.
+app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))
+
+// Start the app as you would normally.
+try app.run()
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.2.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.main.2.swift
@@ -0,0 +1,38 @@
+import Foundation
+import Vapor
+import OpenAPIRuntime
+import OpenAPIVapor
+
+// Define a type that conforms to the generated protocol.
+struct GreetingServiceAPIImpl: APIProtocol {
+    func getGreeting(
+        _ input: Operations.getGreeting.Input
+    ) async throws -> Operations.getGreeting.Output {
+        let name = input.query.name ?? "Stranger"
+        let greeting = Components.Schemas.Greeting(message: "Hello, \(name)!")
+        return .ok(.init(body: .json(greeting)))
+    }
+}
+
+// Create your Vapor application.
+let app = Vapor.Application()
+
+// Create a VaporTransport using your application.
+let transport = VaporTransport(routesBuilder: app)
+
+// Create an instance of your handler type that conforms the generated protocol
+// defininig your service API.
+let handler = GreetingServiceAPIImpl()
+
+// Call the generated function on your implementation to add its request
+// handlers to the app.
+try handler.registerHandlers(on: transport, serverURL: Servers.server1())
+
+// Add Vapor middleware to serve the contents of the Public/ directory.
+app.middleware.use(FileMiddleware(publicDirectory: app.directory.publicDirectory))
+
+// Redirect /openapi to openapi.html, which serves the rendered documentation.
+app.get("openapi") { $0.redirect(to: "/openapi.html", redirectType: .permanent) }
+
+// Start the app as you would normally.
+try app.run()
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.0.yaml b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.0.yaml
@@ -0,0 +1,34 @@
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+paths:
+  /greet:
+    get:
+      operationId: getGreeting
+      parameters:
+        - name: name
+          required: false
+          in: query
+          description: The name used in the returned greeting.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A success response with a greeting.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Greeting'
+components:
+  schemas:
+    Greeting:
+      type: object
+      properties:
+        message:
+          type: string
+      required:
+        - message
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.1.yaml b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.1.yaml
@@ -0,0 +1,36 @@
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+  - url: /api
+    description: The server hosting this document.
+paths:
+  /greet:
+    get:
+      operationId: getGreeting
+      parameters:
+        - name: name
+          required: false
+          in: query
+          description: The name used in the returned greeting.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A success response with a greeting.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Greeting'
+components:
+  schemas:
+    Greeting:
+      type: object
+      properties:
+        message:
+          type: string
+      required:
+        - message
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.html b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server-openapi-endpoints.openapi.html
@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <title>Swift OpenAPI Sample API</title>
+<body>
+  <div id="openapi" />
+  <script src="//unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        url: "openapi.yaml",
+        dom_id: "#openapi",
+        deepLinking: true,
+        validatorUrl: "none"
+      })
+    }
+  </script>
+</body>
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.0.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.0.swift
@@ -5,8 +5,7 @@ let package = Package(
     name: "GreetingService",
     targets: [
         .executableTarget(
-            name: "GreetingService",
-            path: "Sources"
+            name: "GreetingService"
         )
     ]
 )
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.1.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.1.swift
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.2.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.2.swift
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.3.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.3.swift
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.4.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.4.swift
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.5.swift b/Sources/swift-openapi-generator/Documentation.docc/Tutorials/_Resources/server.Package.5.swift

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@`
`60`	`60`	`@Code(name: "Package.swift", file: server.Package.2.swift)`
`61`	`61`	`}`
`62`	`62`	`@Step {`
`63`		`- Now we can update our target to make use of the Swift OpenAPI Generator plugin and add the runtime dependencies for our target.`
	`63`	`+ Now we can update our target to make use of the Swift OpenAPI Generator plugin.`
`64`	`64`	`@Code(name: "Package.swift", file: server.Package.3.swift)`
`65`	`65`	`}`
`66`	`66`	`@Step {`
Original file line number	Diff line number	Diff line change
`@@ -30,5 +30,6 @@`
`30`	`30`	`@TutorialReference(tutorial: "doc:ServerSwiftPM")`
`31`	`31`	`@TutorialReference(tutorial: "doc:ClientSwiftPM")`
`32`	`32`	`@TutorialReference(tutorial: "doc:ClientXcode")`
	`33`	`+ @TutorialReference(tutorial: "doc:Adding-openapi-and-swagger-ui-endpoints")`
`33`	`34`	`}`
`34`	`35`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,8 +5,7 @@ let package = Package(`
`5`	`5`	`name: "GreetingServiceClient",`
`6`	`6`	`targets: [`
`7`	`7`	`.executableTarget(`
`8`		`- name: "GreetingServiceClient",`
`9`		`- path: "Sources"`
	`8`	`+ name: "GreetingServiceClient"`
`10`	`9`	`)`
`11`	`10`	`]`
`12`	`11`	`)`
Original file line number	Diff line number	Diff line change
`@@ -11,8 +11,7 @@ let package = Package(`
`11`	`11`	`],`
`12`	`12`	`targets: [`
`13`	`13`	`.executableTarget(`
`14`		`- name: "GreetingServiceClient",`
`15`		`- path: "Sources"`
	`14`	`+ name: "GreetingServiceClient"`
`16`	`15`	`)`
`17`	`16`	`]`
`18`	`17`	`)`
Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,7 @@ let package = Package(`
`16`	`16`	`],`
`17`	`17`	`targets: [`
`18`	`18`	`.executableTarget(`
`19`		`- name: "GreetingServiceClient",`
`20`		`- path: "Sources"`
	`19`	`+ name: "GreetingServiceClient"`
`21`	`20`	`)`
`22`	`21`	`]`
`23`	`22`	`)`