Documentation tools are often evaluated based on features, flexibility, or how “developer-friendly” they feel. But one critical factor is frequently underestimated: learning curve.

A high learning curve is not just a personal inconvenience. For growing teams, it becomes an organizational tax paid in time, misalignment, and slow knowledge flow. This cost is especially visible when documentation is no longer owned by developers alone, but shared across support, product, QA, and operations teams.

Documentation should adapt to teams, not force teams to adapt to documentation tools.

What a “High Learning Curve” Actually Means for Teams

When teams talk about a “high learning curve,” they’re not saying the tool is unusable. They’re pointing to hidden friction that shows up in day-to-day work.

In practice, a high learning curve means:

• Time spent learning tooling instead of product knowledge
• Longer onboarding for new hires
• Small documentation changes requiring technical intervention
• Fear of “breaking the docs” when making updates

These issues compound as the team grows. What feels manageable for a small engineering group becomes costly when documentation is touched by multiple roles.

High learning curves don’t just slow individuals they slow collaboration.

Why Developer-Only Documentation Breaks in Cross-Functional Teams

Most traditional documentation systems are built with developers in mind. They assume contributors are comfortable with Git, Markdown, pull requests, and build pipelines.

This works well when documentation is strictly technical. It breaks down when documentation becomes a shared responsibility.

Cross-functional documentation often involves:

• Support teams updating FAQs and troubleshooting guides
• Product managers refining feature explanations
• QA teams documenting edge cases and limitations
• Customer success teams maintaining onboarding flows

When only developers can easily contribute, documentation becomes gated. Updates slow down, and teams begin creating their own unofficial sources of truth.

The Hidden Costs of High Learning Curves

The real damage caused by high learning curves is rarely visible in metrics dashboards. These costs appear in indirect but persistent ways.

Common hidden costs include:

• Repeated explanations instead of documented answers
• Engineers context-switching to make minor text edits
• Outdated documentation that lags behind product changes
• Fragmented knowledge spread across multiple tools

Over time, these inefficiencies reduce trust in documentation itself. When teams stop relying on docs, the entire system loses value.

Why Cross-Functional Teams Need Clear Structure + Simple Editing

As documentation expands beyond engineering, clarity becomes more important than flexibility.

Cross-functional teams need documentation systems that provide:

• A clear and intuitive content hierarchy
• Easy-to-find navigation for both contributors and readers
• Editing workflows that don’t require technical setup
• Confidence that updates will publish cleanly

Without these elements, documentation becomes hard to maintain and even harder to scale.

Good documentation isn’t just about what’s written it’s about how easily it can be maintained by the people closest to the knowledge.

Why Not Just Use Git-Based Docs?

Git-based documentation is often the default choice for engineering teams and for good reason. It offers version control, transparency, and tight integration with codebases. For purely technical documentation maintained by a small group of developers, it can be a solid solution.

However, problems arise when Git-based workflows are applied to cross-functional documentation.

Git is optimized for code collaboration, not for content collaboration across roles. When documentation contributors include support, product, QA, and customer success teams, the friction becomes obvious.

Common challenges with Git-based docs include:

• Non-technical contributors struggling with Git concepts like branches, commits, and pull requests
• Fear of breaking builds or causing merge conflicts over simple text edits
• Documentation updates being deprioritized because they require developer involvement
• Slower turnaround for critical changes such as support fixes or clarifications

In theory, everyone can learn Git. In practice, forcing every contributor to do so shifts focus away from documentation quality and toward tooling mastery.

Another limitation is structural. Git-based systems tend to organize content around files and repositories rather than user journeys. As documentation grows, navigation becomes harder to reason about, especially for non-engineers who think in terms of features and workflows rather than directories.

This doesn’t mean Git-based documentation is bad. It means it’s incomplete for teams that rely on multiple contributors with different skill sets.

That’s why modern documentation platforms don’t replace Git they complement it.

How DeveloperHub Reduces Friction for Growing Teams

DeveloperHub is designed with the reality of cross-functional documentation in mind. Instead of forcing all contributors into a single workflow, it supports different roles without fragmenting content.

Non-technical contributors can update documentation using a no-code editor, without touching repositories or build systems.

This enables:

• Faster updates from support and product teams
• Less dependency on engineers for minor changes
• More accurate, up-to-date documentation

At the same time, engineers retain the ability to contribute via Git and Markdown when needed.

Clear Content Hierarchy That Scales

DeveloperHub emphasizes structure from the start. Documentation is organized around products, features, and use cases rather than folders and files.

This structure helps teams:

• Maintain consistency as content grows
• Onboard new contributors faster
• Reduce duplication and confusion

A clear hierarchy turns documentation into a navigable system, not a content dump.

Shared Access Across Roles

Instead of splitting documentation across tools, DeveloperHub keeps everyone working in the same platform.

This shared access means:

• One source of truth for all documentation
• Fewer handoffs between teams
• Better alignment between product, support, and engineering

When documentation is shared, knowledge flows faster and more reliably.

Lower Learning Curve, Better Documentation Quality

Lowering the learning curve doesn’t reduce rigor it increases participation.

When more people can contribute easily:

• Errors are caught earlier
• Gaps in documentation are filled faster
• Content reflects real user questions, not assumptions

Documentation improves not because tools are simpler, but because they remove unnecessary barriers.

Documentation Should Adapt to Teams, Not the Other Way Around

High learning curves are often justified as the price of “powerful” tooling. But in documentation, power isn’t measured by complexity it’s measured by how well knowledge moves through an organization.

The most effective documentation systems are those that scale with teams, support multiple contributors, and remain easy to maintain over time.

DeveloperHub succeeds because it treats documentation as a shared asset, not a developer-only responsibility.

When documentation adapts to teams, collaboration improves, onboarding accelerates, and documentation becomes a strategic advantage instead of a maintenance burden.

Final Thoughts: Learning Curves Shouldn’t Be a Tax on Knowledge

High learning curves are often justified in engineering tools because they unlock deep technical power. But documentation is different. Its primary purpose isn’t to showcase complexity it’s to move knowledge efficiently across teams and to users.

When documentation tools require excessive setup, specialized knowledge, or developer-only workflows, they quietly limit who can contribute. Over time, this leads to slower updates, fragmented sources of truth, and documentation that no longer reflects how the product actually works.

The real question teams should ask isn’t whether a tool is powerful, but whether it scales with the way their organization collaborates.

Cross-functional documentation demands:

• Clear structure instead of clever configuration
• Simple editing instead of fragile pipelines
• Shared ownership instead of centralized gatekeeping

DeveloperHub works well in this space because it doesn’t force a single workflow on everyone. It respects the realities of modern teams, where engineers, support, product, and QA all play a role in maintaining accurate documentation.

In the end, the best documentation systems aren’t the hardest to learn. They’re the ones that quietly disappear into the background, letting teams focus on what actually matters: building, supporting, and improving products.

When documentation adapts to teams rather than the other way around knowledge stops being a bottleneck and starts becoming a competitive advantage.

For years, editor.swagger.io was the place everyone went to sketch out an OpenAPI definition. It was familiar, convenient, and good enough for its time. The problem is simple though: the specification has moved on, tooling expectations have moved on, and that classic editor has not kept pace.

If you work with OpenAPI today especially with the changes landing in 3.2 you need more than syntax colouring. You need proper linting. You need awareness of the latest features. You need a clear structure of your document so you can navigate without hunting through thousands of lines.

So we built it.

A Modern Editor for OpenAPI 3.2

The new API editor at app.developerhub.io/api-editor is designed to be the natural successor to Swagger Editor. It is fully free to use, and you do not need an account.

Here is what it brings to the table:

Full OpenAPI 3.2 support

Every new feature in 3.2 works out of the box. Structured tags, QUERY, updated XML modelling, improved multipart definitions, event streams and more. No hacks or extensions to make the editor understand your document.

Built in linting

The editor flags issues as you type, from simple mistakes to deeper design concerns. You get instant feedback, not silent failures.

Document outline

Large API definitions become manageable. The outline panel shows your tags, paths, components and schema tree, making navigation easy.

No set up, no friction

Open the page, paste your definition, and you are ready to work. Nothing to install. Nothing to configure.

Why this matters

Teams have relied on Swagger Editor for nearly a decade, but the ecosystem has evolved. Tooling needs to reflect the modern specification, not the one from years ago. By offering a free, always up to date editor, we want to make it easier for developers, writers and architects to create accurate and future proof OpenAPI definitions.

If your workflow still leans on editor.swagger.io, it might be time to upgrade. Try the new editor at:

DeveloperHub - API Editor

It works in the browser, it costs nothing, and it already speaks OpenAPI 3.2 fluently.

JSON may dominate modern API design, but XML remains deeply embedded in many enterprise systems. Banks, insurers, logistics networks, public sector systems, and large internal platforms all continue to rely on XML for structured, strongly typed data.

OpenAPI had XML support before, but it was limited. It worked for simple examples, but it could not accurately represent real enterprise XML formats with namespaces, attributes, wrapped arrays, or mixed content.

OpenAPI 3.2 changes that. It introduces clearer, more expressive XML modelling that finally lets teams describe their XML in a faithful and predictable way.

Why XML Needed Attention

OpenAPI 3.1 could express a few basics, but it fell short when modelling XML such as:

• elements that mix attributes and child content
• namespaced payloads
• text content inside complex types
• wrapped arrays with strict naming
• schemas where element names differ from property names

These gaps forced teams to maintain parallel XSDs, rely on proprietary extensions, or manually document XML behaviour in prose.

OpenAPI 3.2 closes many of these gaps.

1. Clear Namespace Support

Before (OpenAPI 3.1)

There was no clean way to define a namespace prefix. Tools guessed from XML examples or ignored the namespace entirely.

xml:
  namespace: "http://acme.com/payments"

No way to say which prefix to use. No way to ensure generated XML matched the contract.

Now (OpenAPI 3.2)

Namespaces can define both the URI and the prefix, allowing accurate generation and parsing.

xml:
  namespace:
    uri: "http://acme.com/payments"
    prefix: "pay"

This is essential for enterprise XML that relies heavily on namespaced elements.

2. More Accurate Representation of Attributes

Before

Attributes were possible but poorly defined. Adding both attributes and text content in the same structure often confused tools.

For example, this structure could not be expressed reliably:

<amount currency="USD">120.50</amount>

Now

OpenAPI 3.2 supports well defined attribute modelling alongside text content.

type: object
xml:
  name: amount
properties:
  currency:
    type: string
    xml:
      attribute: true
  value:
    type: string
    xml:
      text: true

The result closely mirrors the real XML rather than reducing everything to elements.

3. Proper Handling of Wrapped Arrays

Before

Wrapped arrays were supported, but only at a basic level, and always assumed generic wrapping. Complex wrapped structures were impossible to describe.

For example, this common structure:

<items>
  <item>One</item>
  <item>Two</item>
</items>

was supported, but:

<inventory>
  <products>
    <product>...</product>
  </products>
</inventory>

could not be modelled with its multiple layers of specific element names.

Now

OpenAPI 3.2 allows precise control of wrapper element names.

type: array
xml:
  name: products
  wrapped: true
items:
  xml:
    name: product

More complex multi level wrappers now work predictably.

4. More Faithful Complex Types with Text Content

Before

Mixed content was not representable. Any element containing both text and child elements was impossible to model correctly.

For example:

<note priority="high">This is a message <bold>sent today</bold></note>

This simply could not be expressed.

Now

OpenAPI 3.2 introduces clearer rules for text content inside objects.

type: object
xml:
  name: note
properties:
  priority:
    type: string
    xml:
      attribute: true
  content:
    type: string
    xml:
      text: true
  bold:
    type: string

Tools can now produce mixed content more consistently.

5. Cleaner Examples with Namespaces and Structure

XML examples can now be rendered exactly as intended.

Before

Examples were often rendered incorrectly because tools lacked information about prefixes, attribute ordering, or nested wrappers.

Now

An example such as:

examples:
  simple:
    value: |
      <pay:transaction xmlns:pay="http://acme.com/payments">
        <pay:amount currency="USD">120.50</pay:amount>
      </pay:transaction>

can be generated, documented, and validated correctly.

Why This Is Important for Enterprise Teams

These improvements mean:

• fewer separate XSDs to maintain
• fewer vendor extensions
• more predictable generated XML
• documentation that finally matches real world XML
• less confusion for partners integrating with legacy systems
• better long term compatibility for platforms that cannot switch to JSON

It is a practical modernisation of XML within OpenAPI, not a theoretical tweak.

A Step Toward Real Enterprise Support

OpenAPI has been strongly focused on JSON for years, but OpenAPI 3.2 broadens the specification to reflect the reality inside many large organisations.

By strengthening XML modelling, it gives developers a clear, standardised way to describe the formats they actually use.

OpenAPI 3.2 comes with some big, headline features: streaming responses, structured tags, and even a new QUERY method.

But beneath those, there’s a quieter layer of refinements that make life easier for spec authors, tool builders, and documentation teams alike.

These are not the kind of updates that make release notes, but they are the ones that make your API definitions cleaner, stricter, and more predictable.

1. Smarter deprecated handling

Until now, marking something as deprecated: true was purely informational.

It signalled intent, but OpenAPI itself did not give much guidance on what could or should be deprecated.

OpenAPI 3.2 tightens that.

You can now mark schemas, parameters, headers, and even examples as deprecated, not just endpoints or operations.

This allows for more granular control in large APIs.

A single field in a model can be deprecated without confusing users or breaking the schema entirely.

For tool builders, it also means automated documentation can now visually highlight deprecated properties everywhere, not just in endpoint summaries.

2. Explicit defaults are now encouraged

Default values have always existed in OpenAPI, but they were loosely defined.

Different tools interpreted them differently, some treated them as examples, others as enforced fallbacks.

In 3.2, defaults are explicitly clarified to be informational hints to consumers, not behavioural guarantees.

This subtle change aligns OpenAPI with how most servers and SDKs actually behave:

Defaults are what clients may assume, not what servers must enforce.

Tools can now safely display default values without implying server logic.

For documentation and SDK generation, that means fewer misleading assumptions and a clearer contract between client and server.

3. Example and example set improvements

OpenAPI 3.2 refines how examples can be defined and reused.

Examples are now allowed in more places, including within headers, parameters, and links.

This makes it easier to produce richer, context-aware documentation that shows realistic usage patterns.

You can also define multiple named examples more consistently across objects, enabling tools to display example tabs without relying on vendor extensions.

In short: less x-examples clutter and more consistency across your spec.

4. Cleaner schema references

3.2 also revisits how $ref behaves inside schema objects.

Previously, if you referenced a schema and added extra keywords next to it (like description, default, or nullable), tools disagreed on whether those extras should merge or override.

Now, the spec explicitly clarifies that adjacent keywords to $ref must be ignored. They do not merge.

This prevents subtle validation inconsistencies between generators, validators, and documentation tools.

If you want to extend a referenced schema, you now do so explicitly using allOf, as intended.

5. Polished content type rules

The new version also clarifies the relationship between content and schema definitions in request and response bodies.

In 3.0 and 3.1, it was easy to misconfigure a response with both, which led to unexpected validation results.

Now, OpenAPI 3.2 enforces a single source of truth: each media type defines its own schema.

This change improves clarity and helps API editors and linters catch misconfigurations early.

The small things add up

None of these updates will make headlines.

But together, they make OpenAPI 3.2 a more precise, predictable, and developer-friendly specification.

They also highlight the standard’s broader philosophy: evolve carefully, standardise what already works in the community, and make complex APIs just a bit simpler to describe.

So while the new features get the spotlight, it’s these quiet clarifications that will save developers hours in the long run.

One of the quieter updates in OpenAPI 3.2 is support for a new HTTP method: QUERY.

It’s small, but it clarifies something that’s been fuzzy in API design for years — how to represent read-only, query-style operations that aren’t strictly GET.

Why QUERY Exists

Traditionally, REST APIs have used GET for anything that retrieves data. But GET comes with a few assumptions baked in by the HTTP spec:

• Requests must be idempotent (no side effects).
• Requests can’t have a body.
• Parameters have to fit into the URL query string.

That last point has caused trouble.

Some APIs need to send complex filters, nested objects, or large request payloads — all while keeping the operation read-only.

GET doesn’t allow that.

POST does, but using POST for read-only queries violates the spirit of HTTP semantics and breaks cacheability.

The new QUERY method is meant to fix that gap.

What QUERY Does

QUERY is a read-only method that allows a request body.

That means you can write operations like:

paths:
  /search:
    query:
      summary: Search for users
      description: Performs a read-only query with a complex filter
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    country:
                      type: string
                    active:
                      type: boolean
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

This example describes a search endpoint that can take a JSON body instead of a long, hard-to-parse URL query string — while remaining strictly read-only.

Why It Matters

For API consumers, this makes specs and SDKs more predictable.

For API authors, it allows expressive query operations without semantic compromises.

Here’s what changes in practice:

• Cleaner API design: You no longer need to overload POST just because your query has a JSON payload.
• Better caching: Since QUERY is explicitly read-only, it’s easier to implement caching semantics safely.
• Improved documentation: Docs and SDKs can clearly label query endpoints as non-mutating, even with request bodies.

Tooling and Adoption

This is where things get interesting.

While OpenAPI 3.2 now recognises QUERY, many web servers, frameworks, and HTTP libraries don’t — at least not yet. The method is new to the specification world, but not yet part of the core HTTP vocabulary most runtimes expect.

That means you can document QUERY operations today, but whether they’ll run as-is depends on your stack:

• Many frameworks will reject unknown methods until they’re explicitly supported.
• API gateways and reverse proxies (like NGINX or Cloudflare) might block them unless configured to pass them through.
• SDK generators and clients will need to update their request builders to handle QUERY gracefully.

So in practice, QUERY is more of a forward-looking signal than a production-ready feature right now.

Teams can start by using it in their OpenAPI specs to clarify intent — even if they continue serving those endpoints via POST temporarily. Over time, as web servers and tooling catch up, these definitions will become executable, not just descriptive.

A Step Toward Clarity

The addition of QUERY isn’t about introducing something new — it’s about naming what developers have already been doing.

Many APIs have had “read-only POST” endpoints for years. Now, with OpenAPI 3.2, there’s a consistent, standards-based way to describe them.

It’s another small example of how OpenAPI evolves thoughtfully: by turning common patterns into first-class citizens.

One of the most underrated additions in OpenAPI 3.2 is the new support for structured, hierarchical tags.

It doesn’t sound like much at first — tags have existed since the earliest OpenAPI versions. But this change quietly solves one of the most persistent pain points in large-scale API documentation: structure.

The Problem With Flat Tags

Before 3.2, OpenAPI only supported a flat list of tags. Each operation could reference one or more tags, and documentation tools would group endpoints accordingly.

That was fine for small APIs. But as soon as you had dozens or hundreds of operations, the tag list turned into a scrollable wall of names:

users
users-profile
users-notifications
payments
payments-webhooks
analytics
analytics-metrics
analytics-reports

Developers ended up overloading tag names to imply hierarchy — adding hyphens, prefixes, or categories — and relying on their doc viewer to make sense of it. The spec didn’t help you structure it; you just hoped your conventions held up.

What Changes in 3.2

With OpenAPI 3.2, the Tag Object can now be nested and grouped. Tags can belong to categories, subcategories, or other tags — allowing documentation tools and SDK generators to represent APIs in logical hierarchies.

An example might look like this:

tags:
  - name: users
    description: Endpoints related to user management
    summary: Users
  - name: profile
    description: Profile operations
    summary: Profile
    parent: users # <--- Makes profile a child of users
  - name notifications
    description: User notifications
    summary: Notifications
    parent: users
    
  - name: payments
    description: Payment processing and billing

Docs tools can then visualise these relationships as nested menus, collapsible sections, or grouped navigation trees.

Tags are still used the same way as before:

paths:
  /users/{id}/profile:
    get:
      summary: Get user profile
      tags: [profile]
      responses:
        '200':
          description: Returns a user profile

View the Tag Object full details in OpenAPI 3.2 Specification.

Why It Matters

For large organisations, this change brings real clarity.

• Better navigation: You can now organize endpoints by domain, feature, or business area, not just alphabetically.
• Cleaner docs: Readers get a structured hierarchy that mirrors how the product is built.
• Smarter SDKs: Code generators can use tag structure to create namespaces or class groupings automatically.

Fewer naming hacks: No more manual prefixing to simulate folders or sections.

It’s a small spec change with a big downstream effect — especially for teams maintaining large or modular APIs.

A Small Step Toward More Maintainable APIs

Structured tags don’t change how your API behaves — they change how it’s understood.

That’s an equally important part of API design.

This update is about clarity at scale. And for teams that manage complex platforms or multiple product areas, that clarity can make all the difference.

Comparison with x-tagGroups

Before OpenAPI 3.2, the only way to organise tags hierarchically was through the x-tagGroups extension, an unofficial convention popularised by tools.

While it worked well in some ecosystems, it was never part of the OpenAPI standard.

That meant support was inconsistent: some documentation tools rendered tag groups beautifully, while others ignored them entirely.

With structured tags now built into OpenAPI 3.2, this kind of grouping is finally standardised and portable.

You no longer have to rely on vendor-specific extensions or risk losing structure when switching tools.

For API designers and documentation teams, that means one thing: your tag hierarchy will now look the same everywhere.

OpenAPI 3.2 brings native, first‑class ways to describe APIs that send data as a sequence of events instead of a single, monolithic payload. This is a big deal for real‑time apps—LLMs, analytics feeds, chat, logs, and anything that benefits from progressive rendering or lower perceived latency. At a high level, OpenAPI 3.2 formalizes “sequential” media types and lets you specify the schema of each item in the stream using a new itemSchema on a response media type. That means your documentation can be explicit about the shape of each event, not just the overall connection.

• New capability: Use itemSchema under content to define the structure of each streamed event.

Supported sequential media types:

• SSE: text/event-stream
• JSON Lines: application/jsonl
• JSON Sequences: application/json-seq
• Multipart Mixed: multipart/mixed

This unlocks consistent tooling, clearer client expectations, and better validation for streaming APIs.

A quick primer: how streaming differs from “normal” responses

• Normal response: One payload, one schema.
• Streaming response: Many items over time; each item conforms to the itemSchema. The transport stays open while the server emits items; the client processes incrementally.

Common patterns you’ll see:

• SSE for text/token streams in browsers
• JSONL for structured event logs and incremental model outputs
• Multipart for mixed binary/text chunks (e.g., speech + text)
• Sentinel events like [DONE] to cleanly signal the end of a stream

Example: describing an LLM’s streaming API (SSE)

Here’s a minimal but realistic OpenAPI 3.2 spec for a text‑generation endpoint that streams tokens via Server‑Sent Events. The server emits events as they become available; clients render tokens progressively.

openapi: 3.2.0
info:
  title: LLM Streaming API
  version: 1.0.0
paths:
  /generate:
    post:
      summary: Stream generated text from the LLM
      description: |
        Streams model output incrementally using Server-Sent Events (SSE).
        Each event contains a token chunk; a sentinel signals the end.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, prompt]
              properties:
                model:
                  type: string
                  description: Model identifier (e.g., "gpt-4o-mini")
                prompt:
                  type: string
                  description: The input prompt for text generation
                max_tokens:
                  type: integer
                  minimum: 1
                  default: 256
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                  default: 0.7
      responses:
        "200":
          description: Stream of generation events via SSE
          headers:
            Content-Type:
              schema:
                type: string
                enum: ["text/event-stream"]
          content:
            text/event-stream:
              itemSchema:
                oneOf:
                  - type: object
                    required: [event, data]
                    properties:
                      event:
                        type: string
                        enum: ["token"]
                        description: Event type
                      data:
                        type: object
                        required: [text, index]
                        properties:
                          text:
                            type: string
                            description: Token or text chunk
                          index:
                            type: integer
                            minimum: 0
                            description: Incrementing token index
                          logprobs:
                            type: number
                            nullable: true
                            description: Optional per-token log prob
                          finish_reason:
                            type: string
                            nullable: true
                            enum: ["stop", "length", "content_filter", null]
                  - type: object
                    required: [event, data]
                    properties:
                      event:
                        type: string
                        enum: ["summary"]
                      data:
                        type: object
                        properties:
                          usage:
                            type: object
                            properties:
                              prompt_tokens: { type: integer, minimum: 0 }
                              completion_tokens: { type: integer, minimum: 0 }
                              total_tokens: { type: integer, minimum: 0 }
                          model:
                            type: string
                  - type: object
                    required: [event, data]
                    properties:
                      event:
                        type: string
                        enum: ["done"]
                      data:
                        type: string
                        enum: ["[DONE]"]
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
        "429":
          description: Rate limited
        "500":
          description: Server error

Notes:

• text/event-stream matches the SSE transport browsers understand.
• itemSchema with oneOf captures normal token events, an optional final summary, and the explicit end‑of‑stream sentinel.
• Errors follow regular non‑streaming JSON shapes with standard HTTP codes.

Variant: JSON Lines (JSONL) streaming for SDKs and backend clients

If your clients prefer framed JSON instead of SSE, you can offer application/jsonl with the same itemSchema. Each line is one JSON object.

responses:
  "200":
    description: Stream of generation events via JSON Lines
    content:
      application/jsonl:
        itemSchema:
          oneOf:
            - type: object
              required: [type, token]
              properties:
                type:
                  type: string
                  enum: ["token"]
                token:
                  type: object
                  required: [text, index]
                  properties:
                    text: { type: string }
                    index: { type: integer, minimum: 0 }
            - type: object
              required: [type, data]
              properties:
                type:
                  type: string
                  enum: ["done"]
                data:
                  type: string
                  enum: ["[DONE]"]

Designing a great streaming contract

• Be explicit about termination: Include a clear sentinel (e.g., event: "done" with data: "[DONE]") so clients can stop reading deterministically.
• Separate event kinds: Use oneOf to model different event shapes (tokens vs. summary vs. control).
• Carry minimal context: Include a token index, optional finish_reason, and a final summary with usage for billing/UX.
• Document timeouts and reconnection: For SSE you can also expose an SSE retry interval; for clients, document expected timeouts and backoff.
• Error semantics: Prefer failing fast (non‑200) before starting the stream. If you must signal errors mid‑stream, reserve a control event type (e.g., event: "error") and describe it in oneOf.

Client expectations

• SSE clients: Use EventSource in browsers or an SSE library on servers. Parse event and data fields.
• JSONL clients: Read line‑delimited JSON; process each line as one event.
• Backpressure: Streaming responses are pull‑driven by TCP; keep events small and frequent for smoother UX.
• Idempotency: If you support retries, include id/cursor fields so clients can resume safely.

Why this is useful for LLMs

• Faster first token: Users see output immediately, improving perceived latency.
• Progressive rendering: Stream tokens as they’re generated; UIs don’t block.
• Richer telemetry: Emit intermediary signals (e.g., tool_call, reasoning, usage) as distinct event types.
• Interoperability: A standardized spec makes SDKs and gateways simpler to build and maintain.

See the OpenAPI 3.2 specification here.

The OpenAPI spec has always been a careful evolution, not a revolution. Each release nudges things forward without breaking what’s already working. Version 3.2 continues that tradition - it’s incremental, compatible with 3.1, but still meaningful in the ways that matter most to developers, docs teams, and tool builders.

So, what’s changing? And what will it mean for the way we design and document APIs?

A Quick Overview of What’s New

Here are the highlights you’ll notice when 3.2 lands:

1. OAuth device flow support

You can now properly describe device authorisation flows. The spec also adds new metadata fields for OAuth 2 servers and marks a few older OAuth flows as deprecated.

➡️ This means cleaner, more accurate auth documentation and better generator support for modern login patterns.

2. Structured tags

Tags in 3.2 can be hierarchical, not just a flat list. You’ll be able to group operations under categories, subdomains, or even business units.

➡️ Expect to see better grouping in tools like DeveloperHub - fewer long scrolls, more structure.

Further reading: Structured Tags in OpenAPI 3.2: Organising APIs the Way They Deserve

3. A new “QUERY” HTTP method

OpenAPI is adding support for the QUERY method alongside the usual GET/POST/PUT. It’s mostly for APIs that expose custom, read-only search endpoints.

➡️ This brings a few niche APIs out of the “custom extension” shadows and into proper, spec-supported territory.

Further reading: The New QUERY Method in OpenAPI 3.2: A Small Addition That Clears Up a Big Ambiguity

4. Better multipart handling

Multipart/form-data definitions are now clearer, especially when you’re mixing file uploads with structured metadata.

➡️ If you’ve ever struggled to describe an endpoint that uploads an image plus a JSON blob of details, this one’s for you.

5. Event streams and real-time patterns

The spec now acknowledges streaming APIs like server-sent events, as first-class citizens.

➡️ Tooling can start generating and validating them instead of treating streams as weird one-off hacks.

Further reading: Event streaming in OpenAPI 3.2: What changed and why it matters

6. Modernised XML modelling

XML definitions get a significant upgrade. You can now describe attributes, nested structures, and mixed content far more accurately, without awkward workarounds or vendor extensions.

➡️ Enterprise teams with XML based systems finally gain clean, precise schema modelling that lines up with how their APIs actually behave.

Further reading: XML Modelling in OpenAPI 3.2: A Quiet but Important Upgrade for Enterprise Teams

Why This Release Feels Different

OpenAPI 3.2 isn’t flashy but it’s pragmatic. It focuses on the real pain points that show up when you scale: messy docs, patchy auth support, and unclear streaming behavior.

Here’s what that means in practice:

• Cleaner documentation: Hierarchical tags make large APIs actually browsable.
• Smarter SDKs: Code generators can finally infer correct flows for device-based logins.
• More predictable testing: Validators understand streaming and multipart payloads instead of ignoring them.
• Low-risk adoption: Everything is still compatible with 3.1. You can move gradually, feature by feature.

It’s the kind of release that quietly improves your workflow without demanding a rewrite.

A Simple Upgrade Path

Migrating to 3.2 should be painless:

1. Update your OpenAPI toolchain (linters, generators, validators).
2. Change the version number in your spec to openapi: 3.2.0.
3. Start using new features as you need them — nested tags, device flows, multipart fixes.
4. Validate your specs early in CI to make sure your tools all agree.

Because 3.2 is a compatible update, you can introduce new patterns gradually while your existing specs keep working.

Looking Ahead: The Road to 4.0 (“Moonwalk”)

3.2 also lays groundwork for the future. The OpenAPI community is already experimenting with 3.3 and the bigger 4.0 (Moonwalk) release, which aims to simplify nested structures, improve parameter-based responses, and extend support beyond REST.

Think of 3.2 as a safe stepping stone: you get a few of the next-gen ideas today, without waiting for the big version bump.

Final Thoughts

If you live in API specs all day, this update is worth your attention. You’ll spend less time fighting your documentation tools and more time focusing on the design itself.

In short:

✅ Better structure

✅ Better auth support

✅ Better file and stream handling

✅ Zero breaking changes

It’s the kind of quiet progress that keeps the OpenAPI ecosystem healthy — and keeps your documentation future-proof.

Read the full specification here: https://spec.openapis.org/oas/v3.2.0.html

DeveloperHubbers rejoice, we now have a dark theme 🎉

The dark theme extends throughout the documentation pages, API references, landing page and the search functionality.

It is possible to set the dark theme by default for your readers, and also to provide them with a toggle in the top navigation for them to change it.

Here's how it looks:

And the same page in light theme:

Great, how can I use it?

To enable dark theme, you can select it from the "Edit Colours" control at the top right.

Check Theme Toggle if you wish to enable your readers to be able to modify the theme for themselves too.

If you have heavy custom CSS modifications, then you might need to test the existing CSS changes and make changes accordingly. See the Q&A below.

Migrating CSS

To test dark mode on readers' site without saving the setting on the project, open your DevTools and run the following code in console:

window.setTheme('dark');

// Revert with window.setTheme('light');

At this point, feel free to make draft CSS changes. Once you're confident of the changes, publish the CSS changes and set the dark theme as default.

Customising CSS

Our CSS has had a good clean up during the creation of the dark theme. With the introduction of dark theme, we have added more CSS variables that control the look and feel which you can modify.

  --bg-color: #FFF; /* Background color */
  --alt-bg-color: #FFF;  /* Used in some controls for differentiating from background color in dark mode */
  --font-color: #333; /* Font color */
  --heading-color: #444; /* Heading color */
  --category-color: #555; /* Category (in index) color */
  --toc-link-color: #666;  /* TOC text color */
  --table-second-color: #FAFAFA;  /* Alternating table background color */
  --page-border-color: #F1F1F1;  /* Left and bottom page border color */
  --inline-code: #444444; /* Your inline code color */
  --inline-code-bg: #f5f7f7; /* Your inline code background color */

When dark theme is activated, a class .dark-mode is set on document.body which causes the variables to change. Most of the visual changes happen due to the variables change, and only a few other changes are due to specific CSS rules which are applied when .dark-mode is set.

Q&A

Q: Editor looks funny even though I do not have dark theme enabled. How can I solve that?

A: This is probably because you have changed the background/font colour directly using CSS previously (not using the new variables), and have not used the .customise.live selector as in the best practices. Remove these CSS rules to fix it.

Q: My header and link colours do not look good in both light and dark themes. Can I set them up individually?

A: Yes. Set up the colours as usual using the Edit Colours control for light theme, and add the following CSS to change the colour when dark theme is used:

.dark-mode {
  --brand: yellow;
  --link: red;
}

Q: I already have created a dark theme using CSS. Can I keep using mine?

A: While it's possible to keep using yours, we highly recommend that you use our own. That's because 1. Our product is ever-changing and you would need to keep customising your own CSS for dark mode when new features are introduced, 2. Some users do not like the dark theme and would prefer to use the light theme, providing them with a toggle would make their experience better on your docs.

Furthermore, if our exact dark theme colours are not what you need, you can now directly modify them using the CSS variables above.

Q: My frontend application version has been pinned. What do I do now?

A: We pin your frontend application version if you have heavy CSS modifications and we suspect that our CSS is going to conflict with your custom CSS which then would degrade the readers experience. See how to migrate to latest application version. Contact us if you needed further help.

Any product, service, or project needs documentation. Documentation provides instructions and information to users, developers, and stakeholders helping them understand and use a product. There are many types of documentation, each serves a different purpose and addresses the needs of a specific audience. Over the next few minutes, we’ll discuss three common types of documentation that tech businesses have: product documentation, knowledge base, and API references.

What Is Product Documentation?

Product documentation is a type of documentation that provides information about the features and functionality of a product. It explains what the product does, how it works, and how to use it. Product documentation typically originates from the product development team and is designed to help users understand and use the product effectively.

Product documentation can take many different forms, including user manuals, tutorials, and online help guides. It may be provided in printed or digital form, and may be included with the product itself or made available online. Product documentation typically covers a wide range of topics, including installation and setup, user interface and navigation, features and functionality, and troubleshooting and support.

One of the key advantages of product documentation is that it helps users to understand and use the product effectively. By providing clear and concise instructions and explanations, product documentation helps users to quickly learn how to use the product and take advantage of its features and functionality. This can save users time and frustration, and can help to increase the overall satisfaction with the product.

Another advantage of product documentation is that it can help to reduce the need for customer support. By providing clear and comprehensive information, product documentation can help users to solve problems and troubleshoot issues on their own, without having to contact customer support. This can save time and resources for both users and the product development team, and can help to improve the overall customer experience.

What Are Knowledge Bases?

Knowledge base is a type of documentation that focuses on problem solving and customer support. Unlike product documentation, which originates from the product development team, knowledge base documentation typically originates from customer support requests. It is designed to provide users with the information and instructions they need to troubleshoot and resolve common issues and problems.

A knowledge base is typically organised into a series of articles or entries, each addressing a specific problem or issue. These articles may be organised by topic, product, or customer support category, and may include step-by-step instructions, diagrams, and screenshots to help users understand and follow the instructions. Knowledge base articles may be written by the product development team or by customer support specialists, and may be reviewed and updated regularly to ensure accuracy and relevance.

One of the key advantages of a knowledge base is that it provides users with quick and easy access to information and solutions to common problems. By organizing information into a searchable format, a knowledge base allows users to quickly find the information they need, without having to contact customer support. This can save users time and frustration, and can help to improve the overall customer experience.

Another advantage of a knowledge base is that it can help to reduce the workload of the customer support team. By providing a comprehensive resource of information and solutions, a knowledge base can help customer support specialists to quickly and accurately respond to customer inquiries, without having to research and troubleshoot each issue individually. This can save time and resources for the customer support team, and can help to improve their overall efficiency and effectiveness.

What is an API Reference?

API references are a type of documentation that provides information and instructions for developers who are using an application programming interface (API). An API is a set of rules and protocols that allow different software applications to communicate with each other and share data and functionality. API references provide developers with the information they need to understand how an API works, and how to use it to integrate their own applications with the API.

API references typically include detailed information about the API's functions, methods, and parameters, as well as code examples and sample requests and responses. They may also include information about authentication and security, error handling, and other technical details. API references are typically written by the API development team, and may be updated regularly to reflect changes and improvements to the API.

One of the key advantages of API references is that they provide developers with the information they need to effectively use an API. By providing detailed and accurate information, API references can help developers to quickly and easily integrate their applications with the API, without having to spend time and resources on trial and error. This can save developers time and frustration, and can help to improve the overall quality and usability of their applications.

How They All Function Together

The main difference between these types of documentation is their purpose and intended audience. Product documentation is designed to help users understand and use a product effectively, while knowledge bases are focused on providing information and solutions to common problems. APIs, on the other hand, are designed for developers, providing them with the information they need to integrate their own software with other systems or services.

All three types of documentation provide information and instructions to help users, developers, or stakeholders understand and use a product, service, or system. They may be provided in different forms, including written documents, online guides, or reference materials, depending on the needs of the audience. They should all be updated and revised regularly to ensure that the information they provide is accurate, relevant, and up-to-date. Documenting with all of these methods can help to improve user experience, reduce the need for customer support, and increase the overall satisfaction with a product, service, or system.
If you're looking to easily create and integrate product documentation for your products and software services, you should consider using a documentation tool like DeveloperHub. Our tools allow you to collaboratively write, publish, review, analyse and collect feedback on personalised customer-facing documentation the modern way. With no technical skills required or deployment time wasted, you can get your docs up and publicly viewable quickly!

Our third year of operation is over and we couldn't have asked for a more exciting year.

We really believe that we built the best customer-facing documentation platform out there - unparalleled to any other competitor. We have built amazing relationships with our customers and worked on bringing you features that no single platform ever had, to empower you to do things that you never imagined you could do.

Here's a recap of 2020-2021

From our What's New page, we:

• Shipped 92 new features,
• Fixed 53 bugs you reported,
• Had 25 improvements on our existing features,
• Had 2 security updates.

In numbers, so far we now have more than:

• 129,000 pages so far,
• 1300 API References uploaded,
• A WHOPPING 224,000 edits.

There's an announcement of a new product update as well after this.

Let's look back on an amazing year with DeveloperHub

Here are some of the features that we have built throughout 2020-2021:

User Roles

Give every user on DeveloperHub the permissions they only need to make the perfect review process.

Dashboard

Everything you need to start your day with in one view. See all comments on the project, what has been going on lately, and which pages need your help right away.

Embed Mode

Embed your docs in a widget on your own website keeping them in context.

Visual Diff

See how every edit history has changed the documentation with a visual diff.

Major Update to API References

API References have received so much love. From supporting OpenAPI 3, to a slight redesign, to having more languages for auto-generated requests, and so much more!

Community Forums

We released our own Community Forums so you have more transparency on what is going on, and to open a directly channel of communication between our customers.

Search Analytics

Understand how your readers use search, what they are missing and what they look for most, so you can keep on enhancing your documentation.

Feedback

Let your readers tell you what they like and don't like, right from the documentation.

Hosting

Our hosting options got a huge boost. Host DeveloperHub docs on your own existing website or on a subdomain of your website. You can even host multiple projects on the same domain!

The Big Announcement

Custom Login Flow

Log in your readers to your docs securely with JWT Tokens.

How is this any better than password/link sharing?

By using JWT login:

• You control who has access to your docs without having to share a global password/link.
• You can personalise the docs to the logged in reader.
• You control when the access expires.

See more on our docs for how to implement it and use it.

• ✅ Zero dependency on developers for hosting and managing documentation look and feel
• ✅ Reduce technical writing resource requirements by 50%
• ✅ Save up to 30% of time spent in content development

The Benefits

• Empowered technical writers to handle high-frequency documentation updates, increased scalability needs of continuously evolving product documentation and boost productivity of content development.
• Allows technical writers to focus on content development rather than worry about information hosting and layout dependencies. At the same time, the tool gives control by allowing technical writer to retain the flexibility of customisable look and feel in a contemporary documentation layout.
• Intuitive and easy to build simple navigation controls in documentation make it easy for readers to access and search for information.
• WYSIWYG tooling makes collaboration easier among various technical documentation stakeholders involved in content development, review and approval.
• Accelerates quality documentation delivery with modern look and feel.

Company Overview

Founded in 2014, the studied California based company is the leading software platform provider for agile data. The company counts some of the world's largest financial, retail, technology, healthcare, oil & gas, pharmaceutical and manufacturing companies in the Fortune 100 and Global Fortune 500 as its customers.

Due to the nature of their documentation and business, the customer has requested their name to be redacted from this case study which was first published in 2019.

The company hosts over 1000 pages of documentation with DeveloperHub as of the publishing date.

Documentation Objectives

The technical writing team is entrusted with the responsibility of creating quality documentation assets that enhance their customer experience. Working within the time and resource constraints demanded by a continuously evolving cutting edge technology product, the technical writers collaborate across geographies for writing, reviewing, publishing and sharing product information with key stakeholders.

The Challenge

Engineering resources were a bottleneck

Before switching over to DeveloperHub, the studied company used WordPress based content development process that required additional support for hosting their documentation created using WordPress tooling. Following are some of the key issues that made them look for a better solution:

• WordPress usage required dealing with HTML and CSS formats in order to define and manage their documentation layout. This caused an additional dependency of technical writers and content developers on software engineering resources with the requisite skills to handle documentation layout modifications and address issues. The added complexity slowed the rate of content development.
• Hosting of WordPress based documentation was handled by another development resource located in a different geography and that increased dependency and turn-around time for documentation updates.
• Creating contemporary look and feel for documentation required significant effort and resource outside the technical writer’s domain of expertise. Managing change was tedious.
• Another limiting factor with their old documentation process was the complexity in managing the overall documentation structure and its organisation to aid ease of information access using navigation controls.
• The new team members in technical writing team faced steep learning curve with their documentation system that hampered productivity.

Why DeveloperHub?

The complete documentation is now written and published using DeveloperHub. The documentation productivity is no longer hostage to the many issues they were facing with content development, the CSS, plugins and hosting with their older documentation system. With DeveloperHub all the documentation development, review and publishing processes are just a single button-click and that saves a lot of time for them.

Technical writers can focus more on documentation instead of spending time looking for developer resources to help them in fixing issues related to documentation management and hosting. New team members can ramp up faster as the documentation editor is very intuitive, unlike the earlier tool that had a steep learning curve and additional skills besides content development. With DeveloperHub documentation cycles and updates become simpler and faster, giving a boost to API documentation for them.

Their users find DeveloperHub easy to use tool for documentation. The frequent updates and enhancements make the documentation process very interesting and highly productive. The look and feel of the documents generated using DeveloperHub matches closely with what the technical writers require for ease of information access. In addition, the technical writers experienced greater flexibility in content development with the product’s customisation capabilities such as fonts, colours, simple, intuitive navigation controls and various other layout options. Lastly, continuous support from the DeveloperHub support team ensured that all the challenges faced by the information development team were addressed on time helping them in timely release of important product information.

Summary

Technical writing process got a 3X boost with the adoption of DeveloperHub managed documentation service. With its powerful, Medium-like modern WYSIWYG editor, DeveloperHub managed documentation hosting service helped the studied company in writing beautiful user guides, product and API documentation with no dependency on documentation hosting or layout tooling knowledge. Documentation team can now publish it online by a simple click of a button!

Do you need help moving from a static CMS to a realtime modern collaboration tool for customer-facing documentation? Give us a shout.

One of the most interesting, and difficult, aspects of technical writing is the synthesis of subject matter expertise with the needs of various users. You must simultaneously be the plain-language advocate for the novice user while also ensuring that savvy developers can get everything they need from the documentation. It’s tough, but great documentation provides such myriad benefits when done correctly (reduced support load, increased satisfaction, easier sales conversions), it’s worth exploring all the available assets you have to get it right. Having an ironclad review process is a surefire way to progress in that direction, but your review process is likely constrained by time and the schedules of your team members. So, how can you design a review process that’ll be efficient, make end-users happy, and properly leverage your team members’ time?

While there may not be a hard-and-fast rule for review processes, the following guiding principles are a great start for getting your documentation in top shape:

1. Broad, focused documentation reviews
2. Documentation that lives with the code
3. Easily accessible, standardized access

Let’s take a look at each of these individually and how they can apply to your documentation review process.

Broad, Not Deep

Your team members are often specialists in their respective fields, and they should be leveraged as such. Rather than dropping your work into their routine with a vague intention of “making the docs better,” ensure that each reviewer knows what their contribution should be. Let the QA reviewer focus on the known issues that may be absent from the document. Let the Marketing reviewer focus on ensuring the branding and voice of the writing align to the larger goals, and so forth. By having a broad pool of reviewers each with specific, specialized goals, you are able to get the best aspect of each team member while minimizing redundant reviews. Personally, my worst reviewing days have been when I receive six emails back from subject matter experts all pointing out a minor typo or JSON structure issue but no feedback on some of the truly difficult nuances of the feature or API. Everyone is pretty fatigued by the time the document comes back around, and even when the second pass is more intentional, the quality suffers. Likewise, each reviewer should be able to expect when the review will come their way. In my experience, I typically move from design to developer to marketing reviews to ensure accuracy as the focus and document develops. Figure out the singular but focused role each reviewer has and you’ll save time while improving your docs (and potentially watercooler chats too!).

Two-Way Documentation

While standard help center articles typically only surface once the feature is complete, many API documents grow and live with the APIs in the codebase itself. Design or contract-first API methodologies are growing in popularity and continue to be useful in ensuring that critical partner or internal features are at the forefront. Design-first API methods focus on the contract (or human and machine-readable document) and only then build the supporting code, while code-first approaches focus on directly coding in the API from which the contract is later generated. Tracing the current trends, a 2019 State of the API survey found that “while 25% say they are only using a design-first approach, 22% say they are using both the design-first and code-first approach. One-third of the respondents that currently use code-first only say they are moving to a design-first approach.” As such, a key takeaway is that great documentation also adds value back to the design itself.

Personally, I have worked in typical sequential review flows where a raw JSON file is passed to me, I edit and publish it, team members sign off on the new version and the document is largely filed away never to be revisited. The improved documentation never makes its way back to the code comments and future developers and writers miss out on the fruits of the review process. In some cases, the discrepancy can grow between the internally-held and externally-published documents to where there are significant enough differences to impede the full utility of the API; for example, when an endpoint is being refactored, insights gleaned from prior iterations are left out. In companies with significant turnover or growth, new team members or developers may be referencing the same doc from different sources and creating confusion. Making sure that your reviewed, improved copy is the benchmark document allows your team’s hard work to reach its full potential.

Standardized Access

One of the most simple yet easily overlooked aspects of a good review process is the ease of access and drafting. Nothing torpedoes a review process more quickly than having half of it in shared docs, part of it in emails or chats, part on the live site, and so forth. Choose a specific method for drafting and reviewing and stick to it. This will not only save you many organizational headaches, but it will also prevent key edits being lost in the mix of multiple drafts and locations. Personally, I love the new addition of Reviewer roles in DeveloperHub for this very purpose. Developers and QAs can get involved in the same document and leverage different versions to keep the edits intact. Likewise, the finer parts of discussion can be handled with in-app comments before being instantly published. Edits can be reverted at any time to remove any pesky errors, so I can be sure that we can dive into the process without concerns of losing any key feedback.

When it comes to establishing your review process, an ounce of planning is worth a pound of cure. Let me know if any other steps have made your review cycles much better (or worse!) in the comments below. Happy reviewing!

Written by Cody Holden for DeveloperHub.io.

Long gone are days of technical writers merely annotating screenshots, writing FAQs, and serving as an afterthought to development. With the growth of RESTful APIs and microservices, documentation is more important than ever for both accelerating internal development, supporting technical sales and partner teams, and facilitating smooth external integrations. In fact, a 2013 survey by Programmable Web found that complete and accurate documentation was rated as the most important factor in evaluating an API—outranking service-level agreements, price, and even service uptime! Fortunately, as the value of technical documentation has continued to grow, so has the number of tools and services available to support documentation developers. One of the most significant advances in standardizing, improving and building API documentation has been the OpenAPI (Swagger) specification and tool sets.

What is OpenAPI?

OpenAPI is a specification for describing and formatting REST APIs. Written in YAML or JSON, OpenAPI provides a method for documenting the endpoints, operations, required/optional parameters, code samples, and virtually anything you need to communicate about your API. These documents are easily readable by people and machines, can be quickly edited, and even generated directly from the code base.

Formerly known as Swagger before being renamed as the OpenAPI Specification (OAS) in 2016, OAS quickly became the dominant structure for describing REST APIs. By mid-2017, OAS tools exceeded 100,000 downloads per day and have continued to grow. The specification is currently in its third iteration, and the first major release since its move to the OpenAPI Initiative. So, if it has been so successful, what’s the big deal about the latest release? And, more importantly, how can the Swagger spec give your audience the confidence to move forward with your APIs?

What’s in it for me?

As exciting as these developments are to read about, the most important thing is always the tangible, measurable benefit they can bring to your team, documentation, and strategy. For writers learning about OAS 3.0 for their developer docs, the following aspects stand out in contrast to not only other tools but also previous versions of OAS.

Simplified Structure

Regardless of how effective a tool could be, it’s not worth very much if it is impossible to learn, digest, and get up and running. With this in mind, OAS 3.0 features several adjustments to condense and simplify the structure for readability and ease-of-use. Let’s take a look at the YAML document for both OAS 2.0 and 3.0 to highlight some of these comparisons.

Hosts, URLs and Servers

Previously, version 2.0 allowed you to set a host, base URL and schemes to apply across your API documentation. With OAS 3.0, these fields are combined into a servers property, condensing the document while also providing support for multiple base URLs. These can then be defined later in the document to allow individual endpoints to have their own unique base URL if needed. This could be leveraged in the case of staging and production servers.

New Reusable Features

As the “docs-as-code” methodology continues to grow, it’s more important than ever that the structure for documenting APIs mirrors the subject matter itself. OAS 3.0 includes several adjustments to the existing components object to achieve this, with a particular focus on the reusability and consistency of the full document. The five new component objects in OAS 3.0 are:

• callbacks
• links
• examples
• requestBodies
• headers

Let’s take a more in-depth look at how two of these may function in your documentation.

Links

The links object provides a method to describe the relationships between paths. One valuable utility of this field could be directing the user to the next step or the purpose of a value return in the API response. For example, let’s say you have an API where the user enters in a GET request for data on a pet and receives an adoptID in the response. You could leverage the links object to describe how to use that adoptID to submit your adoption request in a subsequent POST.

links:
  GetAdoptIdByPetId:   # <---- arbitrary name for the link
  operationId: getPet
  # or
  # operationRef: '#/paths/~1users~1{adoptId}/get'
  parameters:
  adoptID: '$response.body#/id'

  description: >
    The `adoptID` value returned in the response can be used as
    the `adoptID` parameter in `POST /petStore/{adoptID}`to place an adoption hold on the given pet.

Callbacks

In order to make APIs more dynamic and useful, webhooks and event-driven design are becoming more significant every day. By configuring the Callbacks object, the API documentation can detail additional out-of-band actions that may follow a given request. For example, if you have a client subscribing to your API for given events, they can see the URL where the callback returns data and the parameters of the request body they can expect. You can nest this object within a POST call as detailed in the OAS 3.0 example below:

callbacks:
  # the name `onData` is a convenience locator
  onData:
    # when data is sent, it will be sent to the `callbackUrl` provided
    # when making the subscription PLUS the suffix `/data`
    '{$request.query.callbackUrl}/data':
      post:
        requestBody:
          description: subscription payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  userData:
                    type: string

Examples

The inclusion of easy-to-digest examples is key to converting prospects to partners. With the new Example object, documentation can include rich-text syntax, internally embedded examples (including non-JSON/YAML media types), and URLs to reference external examples that may not have fit smoothly within the JSON/YAML document itself. Examples can be embedded in the model, parameter, request body and response level. If you can’t resist seeing examples of examples, check out how each of these methods is described in the object specification here.

Extended Support for Schema Object

OAS 3.0 expands on examples by supporting multiple media types driven from the schema. For example, for an operation that may contain a binary type for a ‘200’ response and a JSON type for a ‘400’ response, you can document both within the same schema and have this reflected in your document.

Likewise, schema definitions can be further filtered via allOf, anyOf, oneOf to improve API validation. These ensure that the chosen keywords successfully validate against every, at least one, or exactly one schema, respectively. Building on the pet store example above, let’s say the store has both cats and dogs and these objects have both shared and unique attributes. using these validating keywords can be used to ensure the response contains all the fields from both (allOf), all the fields from either (oneOf), or the fields from one or more (anyOf).

With all the new features and flexibility of OpenAPI 3.0, documentation developers can have even more impact on the design, development, and, ultimately, the success of their APIs.

For more information on all of the changes in OAS 3.0, check out the GitHub repository here.

Written by Cody Holden for DeveloperHub.io.