diff --git a/packages/openapi-generator/README.md b/packages/openapi-generator/README.md index 53c79663..3a3f9af1 100644 --- a/packages/openapi-generator/README.md +++ b/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.