Docs api (#208)

* docs edits

* docs edits roughly done

* Update api/openapi-spec/openapi.yaml

Co-Authored-By: JC <[email protected]>

Co-authored-by: JC <[email protected]>

Author: fscelliott

api/openapi-spec/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: Optimizely Agent API
-  description: Optimizely Agent - Full Stack REST API
+  description: Optimizely Agent is a stand-alone, open-source microservice that provides major benefits over using Optimizely SDKs in certain use cases. Its REST API offers consolidated and simplified endpoints for accessing all the functionality of Optimizely Full Stack SDKs. Use this API the control experiments (such as a feature tests). For more info, see https://docs.developers.optimizely.com/full-stack/docs/optimizely-agent. 
   termsOfService: http://optimizely.com/terms/
   license:
     name: Apache 2.0
@@ -13,7 +13,7 @@ security:
 paths:
   /v1/config:
     get:
-      summary: Return the Optimizely Config for the given environment
+      summary: Return the Optimizely config for the given environment
       operationId: getConfig
       description: Return all available experiment and features definitions for this environment.
       responses:
@@ -34,7 +34,7 @@ paths:
     post:
       summary: Track event for the given user.
       operationId: trackEvent
-      description: Track sends event and user details to Optimizely’s analytics backend for the analysis of a feature test or experiment.
+      description: Send event and user details to Optimizely analytics backend, so you can see metrics for an experiment. You can view metrics either on your Results page or as a data export.
       responses:
         '204':
           description: No content, event received
@@ -56,10 +56,7 @@ paths:
     post:
       summary: Activate selected features and experiments for the given user.
       operationId: activate
-      description: Activate iterates over all corresponding features
-        and experiments and returns the decision for the given user.
-        Optionally an impression event will sent to the Optimizely analytics backend
-        for any decision made for and experiment or feature test.
+      description: Returns Optimizely's decision about which features and experiments a given user is exposed to. Optionally sends an impression event to the Optimizely analytics backend for any decision made for an experiment. This endpoint consolidates key functionality from the Full Stack SDKs into one convenient call.
       responses:
         '200':
           description: Valid response
@@ -81,9 +78,7 @@ paths:
     post:
       summary: Override an experiment decision for a user
       operationId: override
-      description: Override a experiment or feature test decision used in future user based decisions. This override is only stored locally
-        in memory for debugging and testing purposes and should not be used
-        for production overrides.
+      description: For debugging or testing. Overrides an experiment and variation decision for a given user, in local memory only. Do not use this endpoint for production overrides.
       responses:
         '200':
           description: Valid response
@@ -105,7 +100,7 @@ paths:
     post:
       summary: Get JWT token to authenticate all requests.
       operationId: getToken
-      description: Generate JWT token for grant_type, client_id and client_secret. It matches the configured values and generates a valid token. Expiration time, and SDK keys to which the token grants access, are provided in configuration.
+      description: Generates valid JWT token for grant_type, client_id, and client_secret, using the values you pass in the request body.  Configure expiration time and SDK keys (to which the token grants access) in Optimizely config. 
       responses:
         '200':
           description: Generates a valid token
@@ -120,7 +115,7 @@ components:
       in: query
       name: disableTracking
       required: false
-      description: Setting to true will disable impression tracking for ab experiments and feature tests.
+      description: Setting to true will disable impression tracking for experiments.
       schema:
         type: boolean
     enabledParam: