Reintroduce OpenAPI v3.2 Specification - with version selector

frontend/javascript/controllers/toggle_controller.js

@@ -1,13 +1,44 @@
 import { Controller } from "@hotwired/stimulus"
 export default class Toggle extends Controller {
   static targets = ["button", "item"]
-  click() {
+
+  connect() {
+    this.handleClickOutside = this.handleClickOutside.bind(this)
+    document.addEventListener('click', this.handleClickOutside)
+  }
+
+  disconnect() {
+    document.removeEventListener('click', this.handleClickOutside)
+  }
+
+  handleClickOutside(event) {
+    if (this.itemTarget.getAttribute("data-toggle-active") === "true" &&
+      !this.element.contains(event.target)) {
+      this.close()
+    }
+  }
+
+  click(event) {
+    event.stopPropagation()
+
     if (this.itemTarget.getAttribute("data-toggle-active") === "true") {
-      this.buttonTarget.setAttribute("aria-pressed", false)
-      this.itemTarget.setAttribute("data-toggle-active", false)
+      this.close()
     } else {
-      this.buttonTarget.setAttribute("aria-pressed", true)
-      this.itemTarget.setAttribute("data-toggle-active", true)
+      this.open()
     }
   }
+
+  open() {
+    this.buttonTarget.setAttribute("aria-pressed", true)
+    this.buttonTarget.setAttribute("aria-expanded", true)
+    this.itemTarget.setAttribute("data-toggle-active", true)
+    this.element.setAttribute("data-toggle-active", true)
+  }
+
+  close() {
+    this.buttonTarget.setAttribute("aria-pressed", false)
+    this.buttonTarget.setAttribute("aria-expanded", false)
+    this.itemTarget.setAttribute("data-toggle-active", false)
+    this.element.setAttribute("data-toggle-active", false)
+  }
 }

frontend/styles/components/dropdown.css

@@ -0,0 +1,89 @@
+.dropdown {
+  position: relative;
+}
+
+.dropdown-trigger {
+  align-items: center;
+  gap: var(--spacing-3);
+  background: none;
+  border: none;
+  color: var(--text-color);
+  padding: 0px;
+  cursor: pointer;
+  font-size: var(--text-base);
+}
+
+.dropdown-label {
+  color: var(--text-color)
+}
+
+.dropdown-caret {
+  display: inline-flex;
+  align-items: center;
+  transition: transform 0.2s ease-in-out;
+}
+
+
+.dropdown[data-toggle-active="true"] .dropdown-caret {
+  transform: rotate(90deg);
+}
+
+.dropdown-menu {
+  position: absolute;
+  right: -6px;
+  background: var(--bg-color);
+  border: var(--border-default);
+  border-radius: calc(var(--spacing-px) + var(--spacing-05));
+  box-shadow: 0 8px 24px rgba(var(--black-rgb), 0.12);
+  z-index: 20;
+  display: none;
+  padding: var(--spacing-1);
+}
+
+.dropdown-menu[data-toggle-active="true"] {
+  display: block;
+  width: 70px;
+}
+
+.dropdown-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+
+  svg {
+    width: var(--spacing-3);
+    height: var(--spacing-3);
+  }
+}
+
+.dropdown-item {
+  margin: 0;
+  padding: var(--spacing-05) calc(var(--spacing-2) + var(--spacing-05));
+}
+
+.dropdown-item > a,
+.dropdown-item > span {
+  display: block;
+  color: var(--text-color, var(--black));
+  text-decoration: none;
+  font-size: var(--text-base);
+}
+
+.dropdown-item:hover:not(.disabled) {
+  background: var(--bg-color-selected);
+  text-decoration: none;
+  border-radius: calc(var(--spacing-px) + var(--spacing-05));
+}
+
+.dropdown-item.is-current {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-direction: row;
+  gap: var(--spacing-4);
+}
+
+.dropdown-item.disabled > span {
+  text-decoration: line-through;
+  cursor: not-allowed;
+}

frontend/styles/index.css

@@ -25,6 +25,7 @@
 
 @import "components/card.css";
 @import "components/search.css";
+@import "components/dropdown.css";
 @import "components/tasklist.css";
 @import "components/toc.css";
 @import "components/timeline.css";

src/_components/guides/version_selector.erb

@@ -0,0 +1,30 @@
+<div class="dropdown" data-controller="toggle">
+  <button class="dropdown-trigger" data-toggle-target="button" data-action="toggle#click" aria-haspopup="true" aria-expanded="false">
+    <span class="dropdown-label"><%= @current_version %></span>
+    <span class="dropdown-caret">
+      <%= svg "images/icons/caret-right.svg" %>
+    </span>
+  </button>
+  <div class="dropdown-menu" data-toggle-target="item" data-toggle-active="false" role="menu">
+    <ul class="dropdown-list">
+      <% @available_versions.each do |version| %>
+        <% if version == @current_version %>
+          <li class="dropdown-item is-current" aria-current="true" data-action="click->toggle#click">
+            <span><%= version %></span>
+            <%= svg "images/icons/checkmark.svg" %>
+          </li>
+        <% elsif page_exist_in_version?(version) %>
+          <li class="dropdown-item">
+            <%= link_to page_url_in_version(version) do %>
+              <%= version %>
+            <% end %>
+          </li>
+        <% else %>
+          <li class="dropdown-item disabled">
+            <span><%= version %></span>
+          </li>
+        <% end %>
+      <% end %>
+    </ul>
+  </div>
+</div>

src/_components/guides/version_selector.rb

@@ -0,0 +1,32 @@
+class Guides::VersionSelector < Bridgetown::Component
+  ENTRIES_VERSIONS = {
+    "3.1" => "openapi_v3-1",
+    "3.2" => "openapi_v3-2"
+  }
+
+  def initialize(entries:, current_url:, current_version:, available_versions:)
+    @entries = entries
+    @current_url = current_url&.to_s
+    @current_version = current_version
+    @available_versions = available_versions
+  end
+
+  def entries_urls_for_version(version)
+    version_key = ENTRIES_VERSIONS[version] # following logic from Builders::Sidebar
+    version_pages = @entries.dig(version_key) || [] # list of groups for this OpenAPI version
+    version_pages_first_level = version_pages.reject { |page| page.dig("items") } # for example /cheatsheet.md
+    version_pages_items = version_pages.flat_map { |page| page.dig("items") }.compact_blank || [] # list of all items / pages displayed for this version.
+
+    version_pages_items.map { |item| item&.resource&.relative_url&.to_s } +
+     version_pages_first_level.map { |page| page&.resource&.relative_url&.to_s }
+  end
+
+
+  def page_exist_in_version?(version)
+    page_url_in_version(version).in?(entries_urls_for_version(version))
+  end
+
+  def page_url_in_version(version)
+    @current_url.gsub(@current_version, version)
+  end
+end

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/_defaults.yml

@@ -7,3 +7,6 @@ display_pagination: true
 display_cta: true
 exclude_from_pagination: true
 slug: openapi-specification
+sidebar_versions:
+- "3.1"
+- "3.2"

src/_guides/openapi/specification/v3.1/advanced/callbacks-webhooks.md

@@ -2,6 +2,7 @@
 title: Callbacks and Webhooks
 authors: phil
 excerpt: Dive into the world of API file uploads in OpenAPI.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/callbacks-webhooks/
 date: 2024-08-07
 ---
 

src/_guides/openapi/specification/v3.1/advanced/error-formats.md

@@ -2,6 +2,7 @@
 title: Handling Error Formats
 authors: phil
 excerpt: Describing HTTP errors efficiently in OpenAPI v3.1.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/error-formats/
 date: 2024-08-07
 ---
 

src/_guides/openapi/specification/v3.1/advanced/file-uploads.md

@@ -2,6 +2,7 @@
 title: Uploading a File
 authors: phil
 excerpt: Dive into the world of API file uploads in OpenAPI.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/file-uploads/
 date: 2024-08-07
 ---
 

src/_guides/openapi/specification/v3.1/advanced/multipart-form-data.md

@@ -2,6 +2,7 @@
 title: Multipart Form Data
 authors: phil
 excerpt: Dive into the world of API file uploads in OpenAPI.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/multipart-form-data/
 date: 2024-08-06
 ---
 

src/_guides/openapi/specification/v3.1/advanced/multiple-content-types.md

@@ -2,6 +2,7 @@
 title: Multiple Content Types with OpenAPI
 authors: phil
 excerpt: 
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/multiple-content-types/
 date: 2024-08-07
 ---
 

src/_guides/openapi/specification/v3.1/advanced/security.md

@@ -2,6 +2,7 @@
 title: Security
 authors: phil
 excerpt: Learn how OpenAPI describes authentication and authorization schemes for your API.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/advanced/security/
 date: 2024-08-07
 ---
 

src/_guides/openapi/specification/v3.1/cheatsheet.md

@@ -3,6 +3,7 @@ title: OpenAPI 3.1 - The Cheat Sheet
 authors: chris
 excerpt: Everything you need to keep in mind when writing an OpenAPI contract, on a one-pager.
 date: 2024-09-12
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/cheatsheet/
 ---
 
 Now that you've roamed through the Complete Guide, let's make long stories short. We have listed the key elements you should always keep in mind when writing a new OpenAPI contract, or maintaining existing ones.

src/_guides/openapi/specification/v3.1/data-models/examples.md

@@ -2,6 +2,7 @@
 title: Examples & Defaults
 authors: phil
 excerpt: Use examples and defaults in OpenAPI to demonstrate API inputs and outputs.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/data-models/examples/
 date: 2024-07-10
 ---
 

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

@@ -2,6 +2,7 @@
 title: JSON Schema in OpenAPI
 authors: phil
 excerpt: Learn how JSON Schema and OpenAPI Schema are similar and how they are different.
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/data-models/json-schema/
 date: 2024-07-17
 ---
 

src/_guides/openapi/specification/v3.1/data-models/representing-xml.md

@@ -2,6 +2,7 @@
 title: Representing XML
 authors: phil
 excerpt: OpenAPI can describe XML APIs with a little work, learn how!
+canonical_url: https://docs.bump.sh/guides/openapi/specification/v3.2/data-models/representing-xml/
 date: 2024-07-24
 ---