<commit_before>== Advanced usage

=== Swagger operationId

Swagger specification supports unique name for each operation using the `operationId` field.
It is recommended to set an operationId for each operation, so that a lot of actions *does not depend on operation `summary` which can change anytime*.
When provided, this `operationId` value will be used primarily to operation `summary + HTTP method` when :
  
  * generating separated operation files : file name
  * generating unique Markup anchors for operations and all sub-items.
  * searching for extra content for operations : operation folder name for plugins (Hand-written descriptions, Dynamic content, etc...)
  
=== Swagger schema title

Swagger2Markup displays inline schemas by decomposing them (when schema is complex). In this process, some intermediate references are generated
using field names which is not always the best choice.
The Swagger document supports JSON Schema `title` items in inline schemas.
It's recommended to use them in inline schemas so that they'll be used primarily to field names and this will lead to a better naming.

.Inline schema without title items
[source,yaml]
----
  InlinePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
----

.Inline schema without title items result 
image::images/untitledSwagger.png[]

.Inline schema without title items
[source,yaml]
----
  InlineTitlePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        title: CategoryModel
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          title: TagModel
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
----

.Inline schema with title items result
image::images/titledSwagger.png[]<commit_msg>advanced_usage documentation (cosmetic)<commit_after>== Advanced usage

=== Swagger operationId

Swagger specification supports unique name for each operation using the `operationId` field.
It is recommended to set an operationId for each operation, so that a lot of actions *does not depend on operation `summary` which can change anytime*.
When provided, this `operationId` value will be used primarily to operation `summary + HTTP method` when :
  
  * generating separated operation files : file name
  * generating unique Markup anchors for operations and all sub-items.
  * searching for extra content for operations : operation folder name for plugins (Hand-written descriptions, Dynamic content, etc...)
  
=== Swagger schema title

Swagger2Markup displays inline schemas by decomposing them (when schema is complex). In this process, some intermediate references are generated
using field names which is not always the best choice.
The Swagger document supports JSON Schema `title` items in inline schemas.
It's recommended to use them in inline schemas so that they'll be used primarily to field names and this will lead to a better naming.

.Inline schema without title items
====
[source,yaml]
----
  InlinePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
----
 
image::images/untitledSwagger.png[]
====

.Inline schema with title items
====
[source,yaml,subs="quotes"]
----
  InlineTitlePet:
    type: object
    required:
      - id
    properties:
      id:
        type: integer
        format: int64
      category:
        type: object
        *title: CategoryModel*
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
      tags:
        type: array
        items:
          type: object
          *title: TagModel*
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
----

image::images/titledSwagger.png[]
====
{'fraction_non_alphanumeric': 0.06423895253682488, 'fraction_numerical': 0.005319148936170213, 'mean_word_length': 2.0347610180012414, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7375620', 'n_tokens_mistral': 1193, 'n_tokens_neox': 1172, 'n_words': 515}