Why generate Swagger 2.0 instead of OpenAPI 3.x?

Some tooling, older internal systems, and certain API gateways still specifically require Swagger 2.0 syntax (a `swagger: "2.0"` document with `definitions` and `securityDefinitions`) rather than the newer OpenAPI 3.x `components` structure. Use the OpenAPI Generator instead if your target actually supports OpenAPI 3.x.

Where do host and basePath come from?

They're parsed directly out of the server URL you provide: the hostname (and port, if present) becomes host, and the URL's path segment becomes basePath (or "/" if the URL has no path). The scheme (http or https) is also detected from the URL and set in the schemes array.

How is the example response generated?

Each path's schema fragment is walked recursively: strings become the literal string "string" (or the schema's first enum value, or an explicit "example" key if present), numbers use their minimum if set, booleans become true, arrays get one sample element, and objects recurse over their properties, producing an examples."application/json" block alongside the schema in the 200 response.

How does bearer auth work in Swagger 2.0, since it doesn't have a native bearer type?

Swagger 2.0's securityDefinitions only support basic, apiKey, and oauth2 types, with no dedicated bearer scheme. Choosing bearer here models it as an apiKey definition reading the Authorization header, with a description noting to send it as "Bearer ", the closest practical equivalent Swagger UI can actually render an input for.

Swagger YAML Generator - Build a Swagger 2.0 Document

Overview

Introduction

Swagger 2.0's YAML structure (host/basePath instead of a servers array, definitions instead of components.schemas, securityDefinitions instead of securitySchemes) is different enough from OpenAPI 3.x that hand-converting between them is a common source of mistakes.

This tool generates a Swagger 2.0 document directly from a plain list of paths, including a derived example response for each, ready to paste into Swagger UI.

What Is Swagger YAML Generator?

A Swagger 2.0 YAML document generator that assembles host/basePath/schemes, per-path operations with inline schemas, derived example responses, and securityDefinitions from repeatable path rows and an auth scheme choice.

It's part of this site's API Tools collection, generating documents in the older but still widely-required Swagger 2.0 dialect specifically (as opposed to OpenAPI 3.x, covered by the separate OpenAPI Generator).

How Swagger YAML Generator Works

The server URL you provide is parsed to extract host, basePath, and scheme (http/https); each path row's method, path, and summary become a Swagger 2.0 operation object, and its schema fragment (parsed as JSON) is attached both as the 200 response's schema and, for POST/PUT/PATCH, as a body parameter's schema.

A recursive example generator walks each schema fragment to produce a representative sample value, which is attached under the response's examples."application/json" key alongside the schema itself, exactly the shape Swagger UI renders in its "Example Value" panel.

When To Use Swagger YAML Generator

Use it when a tool, gateway, or internal system you're integrating with specifically expects Swagger 2.0 syntax rather than OpenAPI 3.x.

It's also useful for quickly producing a Swagger UI-ready document with realistic example responses, without hand-deriving an example for every schema.

Often used alongside OpenAPI Generator, Postman Collection Generator and REST API Config Generator.

Features

Advantages

Targets Swagger 2.0's specific field names (host/basePath/definitions/securityDefinitions) rather than requiring a manual downgrade from an OpenAPI 3.x document.
Derives a realistic example response per path automatically from the same schema fragment used for validation, so Swagger UI's example panel isn't empty.
Parses host, basePath, and scheme directly from a single server URL input instead of requiring them as three separate fields.

Limitations

Swagger 2.0 itself is a legacy specification; new projects should generally prefer OpenAPI 3.x (via the OpenAPI Generator) unless a specific tool requires 2.0.
Bearer auth is modeled as an apiKey-typed Authorization header, since Swagger 2.0 has no native bearer scheme; this is a practical approximation, not a first-class bearer type.
Example generation is a structural heuristic based on type/format/enum/minimum, not a business-rule-aware sample generator.

Examples

A POST path with a request/response schema and an apiKey scheme

Input

title: "Widgets API", version: "1.0.0", serverUrl: "https://api.example.com/v1", authScheme: apiKey, paths: [{method: post, path: /widgets, summary: "Create a widget", schema: {"type":"object","properties":{"name":{"type":"string"}}}}]

Output

swagger: "2.0"
info:
  title: Widgets API
  version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
  - https
paths:
  /widgets:
    post:
      summary: Create a widget
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              name:
                type: string
          examples:
            application/json:
              name: string
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      security:
        - ApiKeyAuth: []
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-Key
    in: header

host and basePath are parsed from the server URL, the schema is used for both the body parameter and the response, and the response also gets a derived example value.

Best Practices & Notes

Best Practices

Prefer the OpenAPI Generator for any new project unless something you're integrating with specifically requires Swagger 2.0.
Review the derived example response and add an explicit "example" key to schema properties in the source fragment where the generic guess isn't realistic enough.
Load the generated YAML into an actual Swagger UI instance to confirm it renders as expected, since Swagger 2.0 tooling can be stricter about field placement than the spec text alone suggests.

Developer Notes

host/basePath/scheme are derived with the browser's native `URL` parser rather than a hand-written regex, which correctly handles ports, credentials, and edge cases like a bare hostname with no path; the example-value walker is a self-contained, depth-capped recursive function scoped to this tool rather than sharing code with the OpenAPI Example Payload Generator, to keep this generator's output independent of that tool's behavior.

Swagger YAML Generator Use Cases

Producing a Swagger 2.0 document for a gateway or internal tool that hasn't migrated to OpenAPI 3.x
Generating a Swagger UI-ready spec with realistic example responses for a small service or prototype
Learning the structural differences between Swagger 2.0 and OpenAPI 3.x by comparing this tool's output to the OpenAPI Generator's

Common Mistakes

Assuming Swagger 2.0's securityDefinitions supports a native bearer type; it doesn't, and this tool's bearer option is an apiKey-header approximation.
Pointing this tool at a server URL with no path segment and expecting a non-"/" basePath; basePath defaults to "/" when the URL has no path.

Tips

If your organization is migrating from Swagger 2.0 to OpenAPI 3.x, generate the same path list with both this tool and the OpenAPI Generator to see the structural differences side by side.

Swagger YAML Generator