docs: update swagger docs

Author: kamilmysliwiec

content/openapi/cli-plugin.md

@@ -91,7 +91,7 @@ You must duplicate both description and example values. With `introspectComments
 roles: RoleEnum[] = [];
 ```
 
-There are `dtoKeyOfComment` and `controllerKeyOfComment` plugin options that you can use to customize how the plugin will set the value for `ApiProperty` and `ApiOperation` decorators respectively. Take a look at the following example:
+There are `dtoKeyOfComment` and `controllerKeyOfComment` plugin options available for customizing how the plugin assigns values to the `ApiProperty` and `ApiOperation` decorators, respectively. See the example below:
 
 ```typescript
 export class SomeController {
@@ -103,13 +103,29 @@ export class SomeController {
 }
 ```
 
-By default, these options are set to `"description"`. This means the plugin will assign `"Create some resource"` to `description` key on the `ApiOperation` operator. Like so:
+This is equivalent to the following instruction:
 
-```ts
-@ApiOperation({ description: "Create some resource" })
+```typescript
+@ApiOperation({ summary: "Create some resource" })
 ```
 
-> info **Hint** For models, the same logic applies but to `ApiProperty` decorator instead.
+> info **Hint** For models, the same logic applies but is used with the `ApiProperty` decorator instead.
+
+For controllers, you can provide not only a summary but also a description (remarks), tags (such as` @deprecated`), and response examples, like this:
+
+```ts
+/**
+ * Create a new cat
+ *
+ * @remarks This operation allows you to create a new cat.
+ *
+ * @deprecated
+ * @throws {500} Something went wrong.
+ * @throws {400} Bad Request.
+ */
+@Post()
+async create(): Promise<Cat> {}
+```
 
 #### Using the CLI plugin
 
@@ -180,11 +196,11 @@ export interface PluginOptions {
   </tr>
   <tr>
     <td><code>controllerKeyOfComment</code></td>
-    <td><code>'description'</code></td>
+    <td><code>'summary'</code></td>
     <td>The property key to set the comment text to on <code>ApiOperation</code>.</td>
   </tr>
   <tr>
-  <td><code>introspectComments</code></td>
+    <td><code>introspectComments</code></td>
     <td><code>false</code></td>
     <td>If set to true, plugin will generate descriptions and example values for properties based on comments</td>
   </tr>

content/openapi/introduction.md

@@ -123,6 +123,15 @@ export interface SwaggerDocumentOptions {
    * @default () => controllerKey_methodKey
    */
   operationIdFactory?: (controllerKey: string, methodKey: string) => string;
+
+  /*
+   * Generate tags automatically based on the controller name.
+   * If `false`, you must use the `@ApiTags()` decorator to define tags.
+   * Otherwise, the controller name without the suffix `Controller` will be used.
+   *
+   * @default true
+   */
+  autoTagControllers?: boolean;
 }
 ```
 

content/openapi/types-and-parameters.md

@@ -230,7 +230,7 @@ breed: string;
 
 #### Raw definitions
 
-In some specific scenarios (e.g., deeply nested arrays, matrices), you may want to describe your type by hand.
+In certain cases, such as deeply nested arrays or matrices, you may need to manually define your type:
 
 ```typescript
 @ApiProperty({
@@ -245,7 +245,27 @@ In some specific scenarios (e.g., deeply nested arrays, matrices), you may want
 coords: number[][];
 ```
 
-Likewise, in order to define your input/output content manually in controller classes, use the `schema` property:
+You can also specify raw object schemas, like this:
+
+```typescript
+@ApiProperty({
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      example: 'Error'
+    },
+    status: {
+      type: 'number',
+      example: 400
+    }
+  },
+  required: ['name', 'status']
+})
+rawDefinition: Record<string, any>;
+```
+
+To manually define input/output content in controller classes, use the `schema` property:
 
 ```typescript
 @ApiBody({