diff --git a/packages/openapi-spec-builder/README.md b/packages/openapi-spec-builder/README.md
index 4464835b4440..a8ec0e111ccb 100644
--- a/packages/openapi-spec-builder/README.md
+++ b/packages/openapi-spec-builder/README.md
@@ -1,6 +1,6 @@
 # @loopback/openapi-spec-builder
 
-Make it easy to create OpenAPI (Swagger) specification documents in your tests
+Make it easy to create OpenAPI specification documents in your tests
 using the builder pattern.
 
 ## Overview
@@ -8,7 +8,7 @@ using the builder pattern.
 Creating a full OpenAPI spec document in automated tests is rather cumbersome,
 long JSON-like objects pollute the test test code and make it difficult for
 readers to distinguish between what's important in the test and what's just
-shared swagger boilerplate.
+shared OpenAPI boilerplate.
 
 OpenApiSpecBuilder utilizes
 [Test Data Builder pattern](http://www.natpryce.com/articles/000714.html) to
@@ -37,22 +37,33 @@ const spec = anOpenApiSpec()
   .build();
 
 // which is equivalent to the following longer form
-
 const spec = new OpenApiSpecBuilder()
   .withOperation('get', '/hello', {
     'x-operation-name': 'greet',
     responses: {
-      '200': {type: 'string'},
+      '200': {
+        description: 'The string result.',
+        content: {
+          'text/plain': {
+            schema: {
+              type: 'string',
+            },
+          },
+        },
+      },
     },
   })
   .build();
 
 // the spec
-
 const spec = {
-  basePath: '/',
-  swagger: '2.0',
+  openapi: '3.0.0',
   info: {title: 'LoopBack Application', version: '1.0.0'},
+  servers: [
+    {
+      url: '/',
+    },
+  ],
   paths: {
     '/hello': {
       get: {
@@ -60,8 +71,12 @@ const spec = {
         responses: {
           '200': {
             description: 'The string result.',
-            schema: {
-              type: 'string',
+            content: {
+              'text/plain': {
+                schema: {
+                  type: 'string',
+                },
+              },
             },
           },
         },
@@ -74,7 +89,7 @@ const spec = {
 ## Related resources
 
 See <https://www.openapis.org/> and
-[version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)
+[version 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
 of OpenAPI Specification.
 
 ## Contributions