From a541cee5e9e76a9e2d05a4d47427dba907e9e4d2 Mon Sep 17 00:00:00 2001 From: Timothy Lai Date: Tue, 20 Sep 2022 09:58:24 -0700 Subject: [PATCH] feat(ls): oas31 docs addtional topics for Media Type object --- .../src/config/openapi/media-type/documentation.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/packages/apidom-ls/src/config/openapi/media-type/documentation.ts b/packages/apidom-ls/src/config/openapi/media-type/documentation.ts index 3920cfc321..9c6ff3a33c 100644 --- a/packages/apidom-ls/src/config/openapi/media-type/documentation.ts +++ b/packages/apidom-ls/src/config/openapi/media-type/documentation.ts @@ -23,7 +23,12 @@ const documentation = [ targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, { - docs: '#### [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)\nEach Media Type Object provides schema and examples for the media type identified by its key.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the content of the request, response, or parameter.\nexample | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.\nexamples | Map[ `string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.\nencoding | Map[`string`, [Encoding Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Media Type Examples\n\n\n\\\nJSON\n```json\n{\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/Pet"\n },\n "examples": {\n "cat" : {\n "summary": "An example of a cat",\n "value": \n {\n "name": "Fluffy",\n "petType": "Cat",\n "color": "White",\n "gender": "male",\n "breed": "Persian"\n }\n },\n "dog": {\n "summary": "An example of a dog with a cat\'s name",\n "value" : { \n "name": "Puma",\n "petType": "Dog",\n "color": "Black",\n "gender": "Female",\n "breed": "Mixed"\n },\n "frog": {\n "$ref": "#/components/examples/frog-example"\n }\n }\n }\n }\n}\n```\n\n\n\\\nYAML\n```yaml\napplication/json: \n schema:\n $ref: "#/components/schemas/Pet"\n examples:\n cat:\n summary: An example of a cat\n value:\n name: Fluffy\n petType: Cat\n color: White\n gender: male\n breed: Persian\n dog:\n summary: An example of a dog with a cat\'s name\n value:\n name: Puma\n petType: Dog\n color: Black\n gender: Female\n breed: Mixed\n frog:\n $ref: "#/components/examples/frog-example"\n```', + /** + * The original documentation has been trimmed in this implementation for readability purposes + * A new custom section `Additional documentation topics` has been added, + * which adds external links back to the original documentation + */ + docs: '#### [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)\nEach Media Type Object provides schema and examples for the media type identified by its key.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the content of the request, response, or parameter.\nexample | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.\nexamples | Map[ `string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.\nencoding | Map[`string`, [Encoding Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Media Type Examples\n\n\n\\\nJSON\n```json\n{\n "application/json": {\n "schema": {\n "$ref": "#/components/schemas/Pet"\n },\n "examples": {\n "cat" : {\n "summary": "An example of a cat",\n "value": \n {\n "name": "Fluffy",\n "petType": "Cat",\n "color": "White",\n "gender": "male",\n "breed": "Persian"\n }\n },\n "dog": {\n "summary": "An example of a dog with a cat\'s name",\n "value" : { \n "name": "Puma",\n "petType": "Dog",\n "color": "Black",\n "gender": "Female",\n "breed": "Mixed"\n },\n "frog": {\n "$ref": "#/components/examples/frog-example"\n }\n }\n }\n }\n}\n```\n\n\n\\\nYAML\n```yaml\napplication/json: \n schema:\n $ref: "#/components/schemas/Pet"\n examples:\n cat:\n summary: An example of a cat\n value:\n name: Fluffy\n petType: Cat\n color: White\n gender: male\n breed: Persian\n dog:\n summary: An example of a dog with a cat\'s name\n value:\n name: Puma\n petType: Dog\n color: Black\n gender: Female\n breed: Mixed\n frog:\n $ref: "#/components/examples/frog-example"\n```\n\n#### Additional documentation topics\n- [Considerations for File Uploads](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#considerations-for-file-uploads)\n\n- [Support for x-www-form-urlencoded Request Bodies](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#support-for-x-www-form-urlencoded-request-bodies)\n\n- [Special Considerations for multipart Content\n](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#special-considerations-for-multipart-content)', targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }], }, ];