docs: rework openapi-generator documentation

DX-669

packages/openapi-generator/README.md

@@ -3,13 +3,24 @@
 The api-ts **openapi-generator** is a command-line utility for converting an io-ts-http
 API specification into an OpenAPI specification.
 
-## Install
+## Contents
+
+1. [Installation](#install)
+2. [Usage](#use)
+3. [Preparing a types package for reusable codecs](#preparing-a-types-package-for-reusable-codecs)
+4. [Defining schemas for custom codecs](#defining-custom-codecs)
+5. [List of supported io-ts primitives](#list-of-supported-io-ts-primitives)
+6. [Generator Reference](#generator-reference)
+   1. [Endpoint documentation](#1-endpoint-documentation)
+   2. [Schema documentation](#2-schema-documentation)
+
+## 1. Install
 
 ```shell
 npm install --save-dev @api-ts/openapi-generator
 ```
 
-## Use
+## 2. Use
 
 The **openapi-generator** assumes the io-ts-http `apiSpec` is exported in the top level
 of the Typescript file passed as an input parameter. The OpenAPI specification will be
@@ -35,7 +46,7 @@ For example:
 npx openapi-generator src/index.ts
 ```
 
-## Preparing a types package for reusable codecs
+## 3. Preparing a types package for reusable codecs
 
 In order to use types from external `io-ts` types packages, you must ensure two things
 are done.
@@ -49,7 +60,7 @@ are done.
    the types in the source code. For example, if the entrypoint is `src/index.ts`, then
    set `"types": "src/index.ts"` in the `package.json`
 
-## Defining Custom Codecs
+## 4. Defining Custom Codecs
 
 When working with `openapi-generator`, you may encounter challenges with handling custom
 codecs that require JavaScript interpretation or aren't natively supported by the
@@ -131,7 +142,7 @@ Follow these steps to create and use a custom codec configuration file:
    definitions for external libraries. For more information on the structure, refer to
    [KNOWN_IMPORTS](./src/knownImports.ts).
 
-## List of supported io-ts primitives
+## 5. List of supported io-ts primitives
 
 - string
 - number
@@ -158,7 +169,7 @@ Follow these steps to create and use a custom codec configuration file:
 - UnknownRecord
 - void
 
-## Generator Reference
+## 6. Generator Reference
 
 This section will highlight all the features that this generator supports, with examples
 to help you add meaningful documentation to your code that will allow clients to use our
@@ -348,3 +359,129 @@ This is what the OpenAPI specification will look like for the route we have buil
   }
 }
 ```
+
+### 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
+
+You can add a description to any schema or field just by adding a jsdoc on top, with a
+description.
+
+```typescript
+import * as t from 'io-ts';
+
+/**
+ * This is a description that will be included in the OpenAPI specification.
+ */
+const schema = t.type({
+  field: t.number,
+});
+```
+
+#### 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.
+
+- `@default[value: any]`
+- `@example [example: any]`
+- `@minLength [length: number]`
+- `@maxLength [length: number]`
+- `@pattern [pattern: regex]`
+- `@minimum [min: number]`
+- `@maximum [max: number]`
+- `@minItems [minItems: number]`
+- `@maxItems [maxItems: number]`
+- `@minProperties [min: number]`
+- `@maxProperties [max: number]`
+- `@exclusiveMinimum`
+- `@exclusiveMaximum`
+- `@multipleOf [num: number]`
+- `@uniqueItems`
+- `@readOnly`
+- `@writeOnly`
+- `@format [format: format]`
+- `@title [title: string]`
+
+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)
+
+```typescript
+include * as t from 'io-ts';
+
+/** @title Sample Schema Title */
+const SampleSchema = t.type({
+  /** @default defaultValueForField1 */
+  field1: t.string,
+  /** @example exampleForField2 */
+  field2: t.string,
+  /** @minLength 4 */
+  field3: t.string,
+  /** @maxLength 6 */
+  field4: t.string,
+  /** @pattern ^[0-9a-f]{32}$ */
+  fieldWithId: t.string,
+  /** @minimum 10 */
+  minField: t.number,
+  /** @maximum 40 */
+  maxField: t.number,
+  /** @minItems 10 */
+  minItemsArray: t.array(t.string),
+  /** @maxItems 50 */
+  maxItemsArray: t.array(t.string),
+  /** @minProperties 3 */,
+  minPropRecord: t.record(t.string, t.string),
+  /** @maxProperties 10 */
+  maxPropRecord: t.record(t.string, t.string),
+  nestedObject: t.partial({
+    /**
+     * @minimum 2
+     * @exclusiveMinimum
+     */
+    exclMin: t.number,
+    /**
+     * @maximum 50
+     * @exclusiveMaximum
+     */
+    exclMax: t.number,
+    /** @multipleOf 5*/
+    multOf: t.number,
+    /** @uniqueItems */
+    arr: t.array(t.string),
+    /** @readOnly */
+    readOnlyField: t.unknown,
+    /** @writeOnly */
+    writeOnlyField: t.unknown,
+    /** @format uuid */
+    uuidField: t.string,
+    /** @title Hello */
+    titleField: t.string
+  })
+})
+```
+
+#### 2.3 Custom Tags
+
+These are some tags that you can use in your schema jsdocs are custom to this generator.
+
+- `@private` allows you to mark any field as in any schema as private. The final spec
+  will have `x-internal: true` for schemas with the `@private` tag.
+- `@deprecated` allows to mark any field in any schema as deprecated. The final spec
+  will include `deprecated: true` in the final specificaiton.
+
+```typescript
+import * as t from 'io-ts';
+
+const Schema = t.type({
+  /** @private */
+  privateField: t.string,
+  /** @deprecated */
+  deprecatedField: t.string,
+  publicNonDeprecatedField: t.string,
+});
+```