diff --git a/packages/@aws-cdk/aws-apigateway/README.md b/packages/@aws-cdk/aws-apigateway/README.md
index bac1284691bab..ff80b34ead5f2 100644
--- a/packages/@aws-cdk/aws-apigateway/README.md
+++ b/packages/@aws-cdk/aws-apigateway/README.md
@@ -153,6 +153,7 @@ and/or payloads returned to a client from a method. A model may be added to a
 REST API as follows:
 
 ```ts
+// Direct addition to REST API
 const beerModel = api.addModel('Beer', 'application/json', {
     $schema: 'http://json-schema.org/draft-04/schema#',
     title: 'Beer',
@@ -164,8 +165,9 @@ const beerModel = api.addModel('Beer', 'application/json', {
       ibu: { type: 'number' },
     },
   },
-  'Simple for defining a beer.');
+  'Simple model for defining a beer.');
 
+// Separate instantiation
 const breweryModel = new apiGateway.Model(this, 'breweryModel', {
   restApi: api,
   name: 'Brewery',
@@ -178,6 +180,7 @@ const breweryModel = new apiGateway.Model(this, 'breweryModel', {
     properties: {
       name: { type: 'string' },
       address: { type: 'string' },
+      // Reference another model
       beers: { type: 'array', items: { $ref: beerModel.referenceForSchema } }
     },
   },