Merge pull request #176 from netlify/doc/add-description

Add `description` field

Author: ehmicky

swagger.yml

@@ -5,7 +5,26 @@ info:
   termsOfService: https://www.netlify.com/legal/terms-of-use/
 externalDocs:
   url: https://www.netlify.com/docs/api/
-  description: Netlify API online documentation
+  description: >-
+    Netlify is a hosting service for the programmable web. It understands your
+    documents and provides an API to handle atomic deploys of websites, manage
+    form submissions, inject JavaScript snippets, and much more. This is a
+    REST-style API that uses JSON for serialization and OAuth 2 for
+    authentication.
+
+
+    This document is an OpenAPI reference for the Netlify API that you can
+    explore. For more detailed instructions for common uses, please visit the
+    [online documentation](https://www.netlify.com/docs/api/). Visit our
+    Community forum to join the conversation about
+    [understanding and using Netlify’s API](https://community.netlify.com/t/common-issue-understanding-and-using-netlifys-api/160).
+
+
+    Additionally, we have two API clients for your convenience:
+
+    - [Go Client](https://github.com/netlify/open-api#go-client)
+
+    - [JS Client](https://github.com/netlify/js-client)
 securityDefinitions:
   netlifyAuth:
     type: oauth2

test/snapshots/main.js.md

@@ -1950,7 +1950,13 @@ Generated by [AVA](https://ava.li).
         },
       },
       externalDocs: {
-        description: 'Netlify API online documentation',
+        description: `Netlify is a hosting service for the programmable web. It understands your documents and provides an API to handle atomic deploys of websites, manage form submissions, inject JavaScript snippets, and much more. This is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.␊
+        ␊
+        This document is an OpenAPI reference for the Netlify API that you can explore. For more detailed instructions for common uses, please visit the [online documentation](https://www.netlify.com/docs/api/). Visit our Community forum to join the conversation about [understanding and using Netlify’s API](https://community.netlify.com/t/common-issue-understanding-and-using-netlifys-api/160).␊
+        ␊
+        Additionally, we have two API clients for your convenience:␊
+        - [Go Client](https://github.com/netlify/open-api#go-client)␊
+        - [JS Client](https://github.com/netlify/js-client)`,
         url: 'https://www.netlify.com/docs/api/',
       },
       host: 'api.netlify.com',