From 9bcaed40d24ff7e9c13c9849bb60ce12044f623d Mon Sep 17 00:00:00 2001
From: Melroy van den Berg <melroy@melroy.org>
Date: Wed, 20 Mar 2024 19:21:02 +0100
Subject: [PATCH] Docs: Convert usage example to OpenAPI v3 spec (#792)

* Docs: Update usage example to OpenAPI v3 spec

* docs: Fix indent
---
 README.md | 57 +++++++++++++++++++++++--------------------------------
 1 file changed, 24 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 674d9785..10b76726 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ A Fastify plugin for serving [Swagger (OpenAPI v2)](https://swagger.io/specifica
 
 If you are looking for a plugin to generate routes from an existing OpenAPI schema, check out [fastify-openapi-glue](https://github.com/seriousme/fastify-openapi-glue).
 
-Following plugins serve swagger/openapi front-ends based on the swagger definitions generated by this plugin:
+Following plugins serve Swagger/OpenAPI front-ends based on the swagger definitions generated by this plugin:
 
 - [@fastify/swagger-ui](https://github.com/fastify/fastify-swagger-ui)
 - [@scalar/fastify-api-reference](https://github.com/scalar/scalar/tree/main/packages/fastify-api-reference)
@@ -17,6 +17,7 @@ See also [the migration guide](MIGRATION.md) for migrating from `@fastify/swagge
 
 <a name="install"></a>
 ## Install
+
 ```
 npm i @fastify/swagger
 ```
@@ -39,48 +40,42 @@ See [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Ref
 
 <a name="usage"></a>
 ## Usage
-Add it to your project with `register`, pass it some options, call the `swagger` API, and you are done!
+
+Add it to your project with `register`, pass it some options, call the `swagger` API, and you are done! Below an example of how to configure the OpenAPI v3 specification with Fastify Swagger:
 
 ```js
 const fastify = require('fastify')()
 
 await fastify.register(require('@fastify/swagger'), {
-  swagger: {
+  openapi: {
+    openapi: '3.0.0',
     info: {
       title: 'Test swagger',
       description: 'Testing the Fastify swagger API',
       version: '0.1.0'
     },
-    externalDocs: {
-      url: 'https://swagger.io',
-      description: 'Find more info here'
-    },
-    host: 'localhost',
-    schemes: ['http'],
-    consumes: ['application/json'],
-    produces: ['application/json'],
+    servers: [
+      {
+        url: 'http://localhost:3000',
+        description: 'Development server'
+      }
+    ],
     tags: [
       { name: 'user', description: 'User related end-points' },
       { name: 'code', description: 'Code related end-points' }
     ],
-    definitions: {
-      User: {
-        type: 'object',
-        required: ['id', 'email'],
-        properties: {
-          id: { type: 'string', format: 'uuid' },
-          firstName: { type: 'string' },
-          lastName: { type: 'string' },
-          email: {type: 'string', format: 'email' }
+    components: {
+      securitySchemes: {
+        apiKey: {
+          type: 'apiKey',
+          name: 'apiKey',
+          in: 'header'
         }
       }
     },
-    securityDefinitions: {
-      apiKey: {
-        type: 'apiKey',
-        name: 'apiKey',
-        in: 'header'
-      }
+    externalDocs: {
+      url: 'https://swagger.io',
+      description: 'Find more info here'
     }
   }
 })
@@ -90,6 +85,7 @@ fastify.put('/some-route/:id', {
     description: 'post some data',
     tags: ['user', 'code'],
     summary: 'qwerty',
+    security: [{ apiKey: [] }],
     params: {
       type: 'object',
       properties: {
@@ -126,14 +122,9 @@ fastify.put('/some-route/:id', {
           foo: { type: 'string' }
         }
       }
-    },
-    security: [
-      {
-        "apiKey": []
-      }
-    ]
+    }
   }
-}, (req, reply) => {})
+}, (req, reply) => { })
 
 await fastify.ready()
 fastify.swagger()