docs: resolve api-ts comments

DX-669

packages/openapi-generator/README.md

@@ -11,8 +11,8 @@ API specification into an OpenAPI specification.
 4. [Defining schemas for custom codecs](#4-defining-custom-codecs)
 5. [List of supported io-ts primitives](#5-list-of-supported-io-ts-primitives)
 6. [Generator Reference](#6-generator-reference)
-   1. [Endpoint documentation](#1-endpoint-documentation)
-   2. [Schema documentation](#2-schema-documentation)
+   1. [Endpoint documentation](#61-endpoint-documentation)
+   2. [Schema documentation](#62-schema-documentation)
 
 ## 1. Install
 
@@ -175,13 +175,13 @@ This section will highlight all the features that this generator supports, with
 to help you add meaningful documentation to your code that will allow clients to use our
 APIs with ease.
 
-### 1. Endpoint documentation
+### 6.1. Endpoint documentation
 
 Given an endpoint defined using `h.httpRoute`, you can add documentation and metadata to
 this endpoint through the use of jsdocs. Here are the following list of attributes that
 are supported.
 
-#### 1.1 Summary
+#### 6.1.1 Summary
 
 The summary is the first line of the jsdoc. This will be added to the OpenAPI
 specification as the endpoints' summary
@@ -193,7 +193,7 @@ specification as the endpoints' summary
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.2 Description
+#### 6.1.2 Description
 
 The description is the next `x` untagged lines of the jsdoc. This will be added to the
 OpenAPI specification as the endpoints' description
@@ -207,7 +207,7 @@ OpenAPI specification as the endpoints' description
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.3 Operation IDs
+#### 6.1.3 Operation IDs
 
 All endpoints must have an `operationId` to be identifiable. You can add an operation ID
 to the specification using the `@operationId` tag in jsdocs. This will add it to the
@@ -224,7 +224,7 @@ OpenAPI specification for this route.
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.4 Tags
+#### 6.1.4 Tags
 
 Tags are how we organize endpoints into different groups on `dev-portal`. There are many
 different tags and tag groups, such as `Wallet`, `Address`, etc.
@@ -243,7 +243,7 @@ for a full list of tags. You can add a tag to your endpoint using the `@tag` jsd
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.5 Private Routes
+#### 6.1.5 Private Routes
 
 There are many instances where you'd want an endpoint to be private, such as `admin` or
 `internal` routes. You can make an endpoint private in documentation by simply adding a
@@ -265,7 +265,7 @@ dev-portal.
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.6 Unstable Routes
+#### 6.1.6 Unstable Routes
 
 If you are working on an endpoint that is unstable, or not completely implemented yet,
 you can add the `@unstable` tag to ensure that documentation is not generated for it (in
@@ -284,7 +284,7 @@ public or internal documentation).
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.7 Examples
+#### 6.1.7 Examples
 
 You can also add example responses to the top level jsdocs of your endpoint, but as
 you'll see in later sections, there are other ways to do this.
@@ -303,7 +303,7 @@ you'll see in later sections, there are other ways to do this.
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.8 Unknown tags
+#### 6.1.8 Unknown tags
 
 Any other tags that are added to this top-level will be classified as an uknown tag, and
 will be placed inside the `x-unknown-tags` field in the OpenAPI specification. You can
@@ -326,46 +326,46 @@ filters endpoints based on the version field in the `x-unknown-tags` field.
 const route = h.httpRoute({ ... })
 ```
 
-#### 1.9 Sample output
+#### 6.1.9 Sample output
 
 This is what the OpenAPI specification will look like for the route we have built.
 
 ```json
 {
-  openapi: 3.03
-  ...,
-  paths: {
+  "openapi": 3.03,
+  // ...,
+  "paths": {
     "/api/v2/sample/route": {
-      get: {
-        summary: "This is the summary",
-        description: "This is description line 1\nThis is description line 2",
-        operationId: "v2.sample.route",
-        example: {
-          object: {
-            key: "value"
+      "get": {
+        "summary": "This is the summary",
+        "description": "This is description line 1\nThis is description line 2",
+        "operationId": "v2.sample.route",
+        "example": {
+          "object": {
+            "key": "value"
           }
         },
-        tag: Wallet,
+        "tag": "Wallet",
         "x-internal": true, // @private
         "x-unstable": true, // @unstable
         "x-unknown-tags": {
-          verion: 3
-        },
-        ...parameters,
-        ...requestBody,
-        ...responses
+          "version": 3
+        }
+        // ...parameters,
+        // ...requestBody,
+        // ...responses
       }
     }
   }
 }
 ```
 
-### 2. Schema Documentation
+### 6.2. Schema Documentation
 
 In addition to adding jsdocs for top-level routes, you can also add jsdocs to
 paremeters, request bodies, and response body schemas.
 
-#### 2.1 Descriptions
+#### 6.2.1 Descriptions
 
 You can add a description to any schema or field just by adding a jsdoc on top, with a
 description.
@@ -381,7 +381,7 @@ const schema = t.type({
 });
 ```
 
-#### 2.2 Supported OpenAPI Tags
+#### 6.2.2 Supported OpenAPI Tags
 
 These are the list of OpenAPI tags that you can put in jsdocs, and they will be included
 in the generated OpenAPI spec.
@@ -409,7 +409,7 @@ in the generated OpenAPI spec.
 Here is an example schema with all these tags in use. Don't worry about the fields, just
 notice the different jsdocs and jsdocs tags for each field. You can also add as many
 tags to one field as you want (provided that the tags don't conflict). You may also add
-[descriptions](#21-descriptions)
+[descriptions](#621-descriptions)
 
 ```typescript
 include * as t from 'io-ts';
@@ -465,7 +465,7 @@ const SampleSchema = t.type({
 })
 ```
 
-#### 2.3 Custom Tags
+#### 6.2.3 Custom Tags
 
 These are some tags that you can use in your schema jsdocs are custom to this generator.