[Docs] remove duplicated content from .yaml pages (#1292)

* [Docs] remove duplicated content from .yaml pages

* add empty description fields

* try empty strings

* update linting rules

* include content from openapi yaml files that were missing from md files

Author: ryancurtis1

openapi/openapi.config.yaml

@@ -18,6 +18,7 @@ lint:
     info-license: off
     paths-kebab-case: off
     boolean-parameter-prefixes: off
+    operation-description: off
 
     # Todo: fix these offenders
     operation-tag-defined: off

openapi/src/connectors.openapi.yaml

@@ -24,8 +24,7 @@ paths:
       tags:
         - Retrieve Connectors
       summary: List Connectors
-      description:
-        $ref: './docs/connectors/list-connectors.md'
+      description: ''
       operationId: get-connectors
       responses:
         '200':
@@ -38,8 +37,7 @@ paths:
       tags:
         - Create Connectors
       summary: Create Connector
-      description:
-        $ref: './docs/connectors/create-connector.md'
+      description: ''
       operationId: create-connector
       requestBody:
         content:
@@ -97,8 +95,7 @@ paths:
       tags:
         - Delete Connectors
       summary: Delete a Project's Connector by Connector Id
-      description:
-        $ref: './docs/connectors/delete-connector.md'
+      description: ''
       operationId: delete-connector
       responses:
         '200':
@@ -118,8 +115,7 @@ paths:
       tags:
         - Retrieve Connectors
       summary: List Connector Logs
-      description:
-        $ref: './docs/connectors/get-history.md'
+      description: ''
       operationId: get-connector-logs
       responses:
         '200':

openapi/src/data-pipelines.openapi.yaml

@@ -60,15 +60,7 @@ paths:
         - Create Pipelines
       operationId: create-warehouse-pipeline
       summary: Create Pipeline
-      description: >
-        This request creates an export pipeline. The `type` parameter defines
-        the kind of pipeline that is initiated. Note that only 2 recurring and 1
-        non-recurring events pipelines (**data_source**: `events`) are allowed
-        per project.
-
-
-        Create API returns the name of the pipeline created. Use the name of the
-        pipeline to check the status of or cancel the pipeline.
+      description: ''
       requestBody:
         required: true
         content:
@@ -252,38 +244,7 @@ paths:
       summary: Get Pipeline
       tags:
         - Retrieve Pipelines
-
-      description: |
-        Given the name of the pipeline this API returns the status of the
-        pipeline. It returns the summary and status of all the recent run export
-        jobs for the pipeline.
-
-
-        **Example Response:** Status with no Summary and a Filter
-
-        ```curl
-        curl https://data.mixpanel.com/api/2.0/nessie/pipeline/status \
-          -u API_SECRET: \
-          -d name="YOUR_PIPELINE_NAME" \
-          -d status="running"
-        ```
-
-        **Example Response:** Status with no Summary and a Filter
-
-        ```json
-        {
-          "canceled": [
-            {
-              "name": "company-july-2016-backfill-hourly-monoschema",
-              "state": "canceled",
-              "last_finish": "0000-12-31T16:00:00-08:00",
-              "run_at": "2016-07-26T00:00:00-07:00",
-              "from_date": "2016-07-26T00:00:00-07:00",
-              "to_date": "2016-07-26T00:00:00-07:00"
-            },
-        }
-        ```
-
+      description: ''
       parameters:
         - $ref: ./common/parameters.yaml#/query/projectId
         - in: query

openapi/src/identity.openapi.yaml

@@ -29,61 +29,7 @@ paths:
         - Identities
       summary: Create Identity
       operationId: create-identity
-      description: |
-        [block:callout]
-        {
-          "type": "info",
-          "body": "You can also use the import endpoint: https://api.mixpanel.com/import/"
-        }
-        [/block]
-
-        **Identify Criteria:**
-        [block:image]
-        {
-          "images": [
-            {
-              "image": [
-                "https://files.readme.io/d0066f0-ID_management_identify_3-HTTP.png",
-                "Identity Management - Identify",
-                960,
-                697,
-                "#cad5da"
-              ]
-            }
-          ]
-        }
-        [/block]
-
-        **Required [Event Object](https://docs.mixpanel.com/docs/how-it-works/concepts#anatomy-of-an-event) attributes**
-
-        [block:parameters]
-        {
-          "data": {
-            "h-0": "Event Object property",
-            "h-1": "Type",
-            "h-2": "Description",
-            "0-0": "**event**",
-            "0-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "0-2": "value must be: `$identify`",
-            "1-0": "**properties**",
-            "1-1": "<span style=\"font-family: courier\">Object</span></br><span style=\"color: red\">required</span>",
-            "2-0": "**properties.distinct_id**",
-            "2-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: green\">optional</span>",
-            "2-2": "The distinct ID post-identification (same as $identified_id - it will be inferred from $identified_id if not included)",
-            "3-0": "**properties.$identified_id**",
-            "3-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "3-2": "A distinct_id to merge with the $anon_id.",
-            "4-0": "**properties.$anon_id**",
-            "4-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "4-2": "A distinct_id to merge with the $identified_id. The $anon_id must be [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier) format and not already merged to an $identified_id.",
-            "5-0": "**properties.token**",
-            "5-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "5-2": "The project token."
-          },
-          "cols": 3,
-          "rows": 6
-        }
-        [/block]
+      description: ''
       requestBody:
         required: true
         content:
@@ -122,65 +68,7 @@ paths:
         - Identities
       summary: Create Alias
       operationId: identity-create-alias
-      description: |
-        [block:callout]
-        {
-          "type": "info",
-          "body": "You can also use the import endpoint: https://api.mixpanel.com/import/"
-        }
-        [/block]
-
-        Mixpanel supports adding an alias to a distinct id. An alias is a new
-        value that will be interpreted by Mixpanel as an existing value. That
-        means that you can send messages to Mixpanel using the new value, and
-        Mixpanel will continue to use the old value for calculating funnels and
-        retention reports, or applying updates to user profiles.
-
-        **Alias Criteria:**
-        [block:image]
-        {
-          "images": [
-            {
-              "image": [
-                "https://files.readme.io/d16f1d3-ID_management_alias_3-HTTP.png",
-                "Identity Management - Alias",
-                960,
-                697,
-                "#cad5da"
-              ]
-            }
-          ]
-        }
-        [/block]
-
-        **Required [Event Object](https://docs.mixpanel.com/docs/how-it-works/concepts#anatomy-of-an-event) attributes**
-
-        [block:parameters]
-        {
-          "data": {
-            "h-0": "Event Object property",
-            "h-1": "Type",
-            "h-2": "Description",
-            "0-0": "**event**",
-            "0-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "0-2": "value must be: `$create_alias`",
-            "1-0": "**properties**",
-            "1-1": "<span style=\"font-family: courier\">Object</span></br><span style=\"color: red\">required</span>",
-            "2-0": "**properties.distinct_id**",
-            "2-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "2-2": "A distinct_id to be merged with the alias.",
-            "3-0": "**properties.alias**",
-            "3-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "3-2": "A new distinct_id to be merged with the original distinct_id. Each alias can only map to one distinct_id.",
-            "4-0": "**properties.token**",
-            "4-1": "<span style=\"font-family: courier\">String</span></br><span style=\"color: red\">required</span>",
-            "4-2": "The project token."
-          },
-          "cols": 3,
-          "rows": 5
-        }
-        [/block]
-
+      description: ''
       requestBody:
         required: true
         content:
@@ -218,35 +106,10 @@ paths:
         - Identities
       summary: Merge Identities
       operationId: identity-merge
+      description: ''
       security:
         - ServiceAccount: []
         - ProjectSecret: []
-      description: |
-        [block:callout]
-        {
-          "type": "danger",
-          "title": "Merging identities is irreversible",
-          "body": "`$merge` is a very powerful tool, so we will only accept `$merge` events that are sent via `https://api.mixpanel.com/import`, which is protected by the project api secret. You **cannot** unmerge `distinct_id`."
-        }
-        [/block]
-
-        **Merge Criteria:**
-
-        [block:image]
-        {
-          "images": [
-            {
-              "image": [
-                "https://files.readme.io/be66940-merge_.png",
-                "Identity Management - Merge",
-                960,
-                446,
-                "#d0d7d3"
-              ]
-            }
-          ]
-        }
-        [/block]
       parameters:
         - in: query
           name: strict

openapi/src/ingestion.openapi.yaml

@@ -1188,70 +1188,7 @@ paths:
       security:
         - ServiceAccount: []
       summary: Replace a Lookup Table
-      description: |
-        Replace the contents of an existing Lookup Table.
-        ***
-        Lookup Tables must be [created via our UI](https://docs.mixpanel.com/docs/data-structure/lookup-tables#how-do-i-upload-a-lookup-table). Once a Lookup Table is created, its contents can be replaced via this API.
-        [block:api-header]
-        {
-          "title": "Validation"
-        }
-        [/block]
-        * The first column of the lookup table is assumed to be the ID of the row. All ID values must be unique.
-        * The first row of the lookup table is a header row. The values in the header must be unique, as each one uniquely identifies a column of the table. These will appear as properties of the lookup table in Mixpanel's UI.
-        * The CSV must be valid according to [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180).
-        * If the `Content-Encoding: gzip` header is supplied, the table will be decompressed before parsing.
-        
-        [block:api-header]
-        {
-          "title": "Types"
-        }
-        [/block]
-        * Integers or floats will be parsed as numbers.
-        * [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamps (`2021-08-21T05:36:01Z`) will parsed as datetimes.
-        * `true` or `false` (case-insensitive) will be parsed as boolean.
-        * Empty fields (two adjacent commas) will be treated as `undefined`
-        * Comma separated, quoted strings in square brackets (`"["Free","Paid","Enterprise"]"`) will be parsed as list of strings.
-        * All other values will be treated as strings.
-
-        [block:code]
-        {
-          "codes": [
-            {
-              "code": "id,artist,genre,is_platinum,name,num_listens,release_date,is_top_40,countries\nc994bb,Drake,Pop,True,Hotline Bling,1700000000,2015-10-18T22:00:00,true,[]\nd8d949,Gipsy Kings,Flamenco,False,Bamboleo,1170000,1987-07-12T05:00:00,false,\"[\"\"US\"\",\"\"CA\"\"]\"\na43fb8,Daft Punk,House,False,Aerodynamic,41000000,2001-03-12T07:30:00,false,\"[\"\"IN\"\"]\"\n",
-              "language": "text",
-              "name": "sample.csv"
-            }
-          ]
-        }
-        [/block]
-
-        [block:api-header]
-        {
-          "title": "Errors"
-        }
-        [/block]
-        Lookup Tables are replaced in their entirety or not replaced at all. When the Lookup Table fails to meet the above validation, we return an error that looks as follows:
-        [block:code]
-        {
-          "codes": [
-            {
-              "code": "{\n  \"error\": \"some data points in the request failed validation\",\n  \"failed_records\": [\n    {\n      \"index\": 2,\n      \"message\": \"invalid row: row indexes 1 and 2 have the same primary key\"\n    },\n    {\n      \"index\": 3,\n      \"message\": \"invalid row: wrong number of fields\"\n    }\n  ],\n  \"status\": 0\n}",
-              "language": "json"
-            }
-          ]
-        }
-        [/block]
-        We will return at most the first 10 rows that failed validation.
-        [block:api-header]
-        {
-          "title": "Limits"
-        }
-        [/block]
-        This endpoint will return a 429 error if called more than 100 times in a rolling 24 hour window. We recommend updating lookup tables at most hourly to stay within this limit.
-
-        This endpoint will return a 413 error if a Lookup Table exceeds 100MB uncompressed. In practice, this translates to 1-2M rows. If you have a lookup table that exceeds the limit, we recommend pruning the number of columns to those that are useful to analysis. Removing long URLs or user-generated content can bring a lookup table within this limit. If you still exceed the limit, please reach out to us at [email protected] -- we'd love to hear your use case!
-        
+      description: ''
       parameters:
         - in: path
           name: id