OpenAPI v3.2 guide

Revert #403, back to #359 with a single commit

Old commits list:
- "oas: default example was wrong""
- "copy oas 3.1 with oas 3.2 changes""
- "more about tag kind and parent""
- "security scheme deprecation""
- "response description is optional""
- "response no content means no content""
- "security schemes can be references now too""
- "removed trailing slash""
- "use newer rfc relative ref pointer links""
- "more about tags, oauth2, and server names""
- "guide: pagination""
- "quick punt at streaming""
- "fix broken link""
- "improved json streaming guide""
- "new and improved json streaming guide""
- "couple more tweaks""
- "link to new spec""

Author: Polo2

src/_data/sidebars/guides/openapi/v3-2.yml

@@ -0,0 +1,85 @@
+collection_name: guides
+root: /guides/openapi/specification/v3.2
+resources:
+  - type: category
+    label: Introduction to OpenAPI
+    items:
+      - label: What is OpenAPI?
+        link: /introduction/what-is-openapi/
+      - label: History and Evolution of OpenAPI
+        link: /introduction/history/
+      - label: Benefits of Using OpenAPI
+        link: /introduction/benefits/
+  - type: category
+    label: Understanding OpenAPI Structure
+    items:
+      - label: Basic Structure
+        link: /understanding-structure/basic-structure/
+      - label: Defining API Servers
+        link: /understanding-structure/api-servers/
+      - label: Paths and Operations
+        link: /understanding-structure/paths-operations/
+      - label: Parameters (Path, Query, Header, and Cookie)
+        link: /understanding-structure/parameters/
+      - label: Parameter Serialization
+        link: /understanding-structure/parameter-serialization/
+      - label: HTTP Requests
+        link: /understanding-structure/http-requests/
+      - label: HTTP Responses
+        link: /understanding-structure/http-responses/
+      - label: Components Section
+        link: /understanding-structure/components/
+  - type: category
+    label: Defining Data Models
+    items:
+      - label: Schema and Data Types
+        link: /data-models/schema-and-data-types/
+      - label: JSON Schema in OpenAPI
+        link: /data-models/json-schema/
+      - label: Examples and Default Values
+        link: /data-models/examples/
+      - label: Schema Composition
+        link: /data-models/schema-composition/
+      - label: Representing XML
+        link: /data-models/representing-xml/
+  - type: category
+    label: Advanced OpenAPI Specification
+    items:
+      - label: Splitting OpenAPI into Multiple Documents
+        link: /advanced/splitting-documents-with-ref/
+      - label: Multipart Form Data
+        link: /advanced/multipart-form-data/
+      - label: Pagination
+        link: /advanced/pagination/
+      - label: File Uploads
+        link: /advanced/file-uploads/
+      - label: Supporting Multiple Content Types
+        link: /advanced/multiple-content-types/
+      - label: Handling Error Formats
+        link: /advanced/error-formats/
+      - label: Security (Authentication and Authorization)
+        link: /advanced/security/
+      - label: Callbacks and Webhooks
+        link: /advanced/callbacks-webhooks/
+      - label: JSON Streaming
+        link: /advanced/json-streaming/
+  - type: category
+    label: Documenting APIs
+    items:
+      - label: Adding Descriptions and Summaries
+        link: /documentation/descriptions-and-summaries/
+      - label: Grouping Operations with Tags
+        link: /documentation/grouping-operations-with-tags/
+      - label: Linking to External Documentation
+        link: /documentation/external-documentation/
+  - type: category
+    label: Extending OpenAPI
+    items:
+      - label: Custom Extensions and Vendor Extensions
+        link: /extending/extensions/
+      - label: Enriching OpenAPI with Overlays
+        link: /extending/overlays/
+  - label: The Perfect Modern OpenAPI Workflow
+    link: /the-perfect-modern-openapi-workflow/
+  - label: The Cheat Sheet
+    link: /cheatsheet/

src/_guides/openapi/specification/v3.1/data-models/schema-and-data-types.md

@@ -220,14 +220,14 @@ Setting a `default` lets people and code know what to do when a value has not be
 
 ```
 type: string
+default: pending
 enum:
   - pending
   - fulfilled
   - archived
 ```
 
-
-
+This is useful for properties that have a common or expected value, allowing you to avoid having to specify it every time.
 
 ### minimum & maximum
 

src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md

@@ -15,22 +15,26 @@ Typically, OpenAPI tags are used to group related endpoints in a meaningful way,
 
 ```yaml
 tags:
-  - name: Stations
+  - name: stations
+    summary: Stations
     description: | 
       Find and filter train stations across Europe, including their location
       and local timezone.
     externalDocs:
       description: Read more
       url: http://docs.example.com/guides/stations
-  - name: Trips
-    description: | 
+  - name: trips
+    summary: Trips
+    description: |
       Timetables and routes for train trips between stations, including pricing
       and availability.
-  - name: Bookings
+  - name: bookings
+    summary: Bookings
     description: | 
       Create and manage bookings for train trips, including passenger details
       and optional extras.
-  - name: Payments
+  - name: payments
+    summary: Payments
     description: |
       Pay for bookings using a card or bank account, and view payment
       status and history.
@@ -40,20 +44,28 @@ tags:
       > before the expiry date 
 ```
 
+The `name` property is required and must be unique across all tags in the document. It is used to reference the tag in the `tags` property of an endpoint, and is generally considered as a variable name for the tag.  
+
+OpenAPI v3.2 introduced the `summary` property, which is a human-readable short description of the tag. Often this is just a Case Title version of the `name` but it can be anything, just keep it short so it fits nicely into API reference documentation navigation menus as that's generally what it's used for.
+
+The `description` property can be used to provide more detailed information about the tag. This can be really in depth and fully explain what the concept means, because e.g: Account or Unit could mean infinite different things in different domains. 
+
+You can also link to external documentation using the `externalDocs` property.
+
+## Referencing Tags in Endpoints
+
 Once you've created these tags, you can use them to group related endpoints in your API using the `tags` property on the endpoint as follows:
 
 ```yaml
 paths:
   /stations:
     get:
       summary: Get a list of train stations
-      tags:
-        - Stations
+      tags: [ stations ]
   /trips:
     get:
       summary: Get available train trips
-      tags:
-        - Trips
+      tags: [ trips ]
 ```
 
 You can also apply multiple tags to an operation:
@@ -63,9 +75,7 @@ paths:
   /bookings/{bookingId}/payment:
     post:
       summary: Pay for a Booking
-      tags:
-        - Bookings
-        - Payments
+      tags: [ bookings, payments ]
 ```
 
 ## Benefits of OpenAPI Tags
@@ -75,15 +85,17 @@ Tags are a powerful tool for improving the usability of your OpenAPI document. B
 ### Tags Can Describe Endpoint Groups
 
 When specifying your tags in the root level of your API contract, you can give context to the tag using the `description` property.
+
 Let’s take [Bump.sh API documentation](https://bump.sh/demo/doc/bump). Here is how the `Diffs` tag is created and described in [Bump.sh API Contract](https://developers.bump.sh):
 
 ```yaml
 tags:
-  - name: Diffs
+  - name: diff
+    summary: Diffs
     description: Diff summary of changes in the API
 ```
 
-The documentation will show the `Diffs` property like this:
+The documentation will show the `diff` tag like this:
 
 ![Diff attribute in the generated API documentation](/images/guides/diff_attribute.png)
 [*See it live*](https://bump.sh/demo/doc/bump/group/endpoint-diffs)
@@ -98,7 +110,7 @@ In the code snippet below, the `externalDocs` property provides a link to a URL
 
 ```yaml
 tags:
-  - name: Diffs
+  - name: diff
     description: Diff summary of changes in the API
     externalDocs:
       description: More details about Diff
@@ -115,17 +127,23 @@ When specifying your OpenAPI or AsyncAPI tags in the root of your API contract,
 
 ```yaml
 tags:
-  - name: Diffs
+  - name: diff
+    summary: Diffs
     description: Diff summary of changes in the API
-  - name: Ping
+  - name: ping
+    summary: Ping
     description: Monitoring status endpoints
-  - name: Previews
+  - name: preview
+    summary: Previews
     description: Preview for documentation file
-  - name: Versions
+  - name: version
+    summary: Versions
     description: Deploy your API contracts
-  - name: Validations
+  - name: validation
+    summary: Validations
     description: Check & validate your API contracts
-  - name: Hubs
+  - name: hub
+    summary: Hubs
     description: Interact with your Hubs
 ```
 
@@ -143,18 +161,19 @@ Now that you understand what tags are and their benefits, you'll see some best p
 ### Tag Everything
 
 When using tags, make sure you tag all your endpoints.
-Notice how all diff-related endpoints are tagged with the `Diffs` tag in this snippet:
+
+Notice how all diff-related endpoints are tagged with the `diffs` tag in this snippet:
 
 ```yaml
 paths:
   /diffs:
     post:
-      tags: [ Diffs ]
+      tags: [ diff ]
       summary: Create a diff
       [...]
   /diffs/{id}:
     get:
-      tags: [ Diffs ]
+      tags: [ diff ]
       summary: Fetch detailed information from an existing diff
       [...]
 ```
@@ -171,22 +190,25 @@ To ensure your endpoints remain logically grouped and ordered, always tag every
 
 When defining the list of tags in the root of your API contract, make sure not to duplicate tag names. Since the tag's `name` property links an endpoint to a tag, duplicate names are likely to confuse developers looking at the API contract.
 
-The code snippet below contains the root Tag Object in an API contract. Notice how the `Validations` tag has been duplicated, and the second definition contains a different description to the first:
+The code snippet below contains the root Tag Object in an API contract. Notice how the `validation` tag has been duplicated, and the second definition contains a different description to the first:
 
 ```yaml
 tags:
-  - name: Diffs
-    description: Diff summary of changes in the API
-  - name: Versions
-    description: Deploy your API contracts
-  - name: Validations
-    description: Check & validate your API contracts
-  - name: Hubs
-    description: Interact with your Hubs
-  - name: "Documentation change"
-    description: Check & validate your API contracts
-  - name: Validations
-    description: Validate your API status
+  - name: diff
+    summary: Diffs
+    description: Diff summary of changes in the API.
+  - name: version
+    summary: Versions
+    description: Deploy your API contracts.
+  - name: validation
+    summary: Validations
+    description: Check & validate your API contracts.
+  - name: documentation_change
+    summary: Documentation Change
+    description: Check & validate your API contracts.
+  - name: validation
+    summary: Validations
+    description: Validate your API status.
 ```
 
 These duplicate tags would confuse anyone trying to understand your API contract, as they wouldn't know which of the two tag definitions an endpoint belongs to.
@@ -195,21 +217,23 @@ Instead, make sure you define and describe every tag only once in the root Tag O
 
 ```yaml
 tags:
-  - name: Diffs
-    description: Diff summary of changes in the API
-  - name: Versions
-    description: Deploy your API contracts
-  - name: Validations
-    description: Check & validate your API contracts
-  - name: Hubs
-    description: Interact with your Hubs
-  - name: "Documentation change"
-    description: Check & validate your API contracts
+  - name: diff
+    summary: Diffs
+    description: Diff summary of changes in the API.
+  - name: version
+    summary: Versions
+    description: Deploy your API contracts.
+  - name: validation
+    summary: Validations
+    description: Check & validate your API contracts.
+  - name: documentation_change
+    summary: Documentation Change
+    description: Check & validate your API contracts.
 ```
 
 ### Define All Your OpenAPI Tags in the Root Tag Object
 
-The OpenAPI specification [doesn't require you to define all your tags in the root Tag Object of your API contract](https://swagger.io/specification/#:~:text=A%20list%20of,MUST%20be%20unique). This means you can add a tag to an endpoint without listing it in the root Tag Object, but this is a bad idea. You won't be able to control what order the OpenAPI tags should appear in, and you won't be able to add a description or provide a link to external documentation for that tag. It can also confuse developers browsing your API contract as they won't see a list of all the tags used in the API contract.
+The OpenAPI specification [doesn't require you to define all your tags in the root Tag Object of your API contract](https://spec.openapis.org/oas/v3.1.0#:~:text=A%20list%20of,MUST%20be%20unique). This means you can add a tag to an endpoint without listing it in the root Tag Object, but this is a bad idea. You won't be able to control what order the OpenAPI tags should appear in, and you won't be able to add a description or provide a link to external documentation for that tag. It can also confuse developers browsing your API contract as they won't see a list of all the tags used in the API contract.
 
 As an example, consider the code snippet below where the `Previews` and the `Ping` tags has not been included in the root Tag Object:
 

src/_guides/openapi/specification/v3.1/extending/overlays.md

@@ -103,7 +103,7 @@ actions:
 
 These descriptions (which can be much longer and full of even more Markdown) will then show up in API Documentation, pride of place, ready to explain the concepts to the user before they get stuck into what specific endpoints are about.
 
-![Untitled](/images/guides/efficient-tech-writing-process/bump-tag-description.png)
+![A screenshot of Bump.sh generated API documentation on the Operations tag page, with the Markdown from the above example rendered as HTML including a link to the contact us page.](/images/guides/efficient-tech-writing-process/bump-tag-description.png)
 
 Here’s the tag description rendered in Bump.sh.
 

src/_guides/openapi/specification/v3.1/understanding-structure/basic-structure.md

@@ -63,7 +63,7 @@ Only the following fields are **required**:
 - `title` - Your API probably has a name, and if not perhaps now is a good time to think of one thats useful for public consumption.
 - `version` - The version of your OpenAPI document, which does not have to related to the API version, or the OpenAPI Specification version. 
 
-Updating the version number when you make changes is pretty common, and keeping it seperate from the API version at first feels a little bit odd, but soon makes sense. After all, you can fix issues with the OpenAPI document that produce no change whatsoever in the API, and vice-versa. 
+Updating the version number when you make changes is pretty common, and keeping it separate from the API version at first feels a little bit odd, but soon makes sense. After all, you can fix issues with the OpenAPI document that produce no change whatsoever in the API, and vice-versa. 
 
 These other fields are **optional**: 
 
@@ -351,7 +351,7 @@ The name is often displayed to users in human-readable documentation so its best
 Putting it all together, here is a simple example of an OpenAPI document:
 
 ```yaml
-openapi: 3.0.3
+openapi: 3.1.1
 info:
   title: Sample API
   description: A sample API to illustrate OpenAPI concepts.

src/_guides/openapi/specification/v3.2/_defaults.yml

@@ -0,0 +1,2 @@
+sidebar_version: "v3.1"
+sidebar_name: openapi_v3-1