What is Swagger? Swagger vs OpenAPI Explained

What is Swagger?

Swagger is the family of open-source tools, most notably Swagger UI and Swagger Editor, built around the OpenAPI Specification, the standard format for describing HTTP APIs. You write one machine-readable description of your API, and tools turn it into interactive documentation, client and server code, mock servers and tests. "Swagger" was also the original name of the specification itself.

Swagger vs OpenAPI

The two names cause most of the confusion, so here is the split:

• OpenAPI Specification (OAS) is the format: a JSON or YAML document describing endpoints, parameters, request and response schemas and authentication. The latest published version at the time of writing is 3.2.1.
• Swagger is the old name of the specification (until the rename on 1 January 2016) and today the name of SmartBear's tooling around it. A "Swagger 2.0 file" uses the old naming and is still read by Swagger UI.
• Swagger UI renders an OpenAPI description as browsable documentation and lets readers try out each operation. It reads Swagger 2.0 and OAS 3.x files.
• Swagger Editor is an editor for writing OpenAPI descriptions with live preview and validation.

The history, briefly: Swagger was created in 2011 and open-sourced that September. In November 2015 SmartBear helped create the OpenAPI Initiative under the Linux Foundation, and the specification became OpenAPI.

What an OpenAPI description looks like

Only openapi and info (with title and version) are mandatory, plus at least one of paths, components or webhooks. A small working example:

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    get:
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

From this one file, tools can generate the documentation page, a typed client, a server stub and a mock server. Read the full format in the OpenAPI Specification.

Design-first or code-first

• Design-first: write the description, review it with the people who will consume the API, then generate stubs and clients. Frontend teams can work against a mock (API mocking) while the backend is built. This matches an API-first approach.
• Code-first: annotate the code and let the framework generate the description. It is quick to start, but the description is only as accurate as the annotations.

Common mistakes

• Letting the spec drift from the real API. A description nobody checks goes stale. Run contract tests in CI and check the live API against it.
• No examples. Add example values to schemas, so generated docs and mocks are usable.
• Undocumented errors. List 4xx and 5xx responses, not only 200.
• Wrong security scheme. If authentication is described incorrectly, generated clients and "Try it out" fail with 401.
• Treating it as GraphQL or gRPC tooling. OpenAPI describes HTTP APIs. GraphQL and gRPC have their own schema languages.

Swagger, API testing and monitoring

A description is only a promise about behavior. API testing checks the promise before release, and API monitoring checks it continuously in production. LoadFocus API Monitoring can import an OpenAPI 3.x or Swagger 2.0 spec and generate one monitor per operation, with assertions on status code, body, headers and response time. Free checks run every 5 minutes.

The same description can seed performance tests: importing cURL, HAR, Postman and OpenAPI into load tests shows how. For hands-on request testing, see the online API tester guide.

FAQ: Swagger and OpenAPI

Is Swagger the same as OpenAPI?

Not quite. OpenAPI is the specification. Swagger is the original name of that specification and now the name of the tools around it, such as Swagger UI and Swagger Editor.

Is Swagger free?

Swagger UI and the other open-source tools are free to use. SmartBear also sells hosted products; check their site for current plans.

Which version should I use?

Use a current 3.x version if your tools support it. The latest published version is 3.2.1; many tools still target 3.0 or 3.1, so check what your documentation renderer and code generator accept.

Swagger or Postman?

They do different jobs. OpenAPI describes the API, and Postman is a client for exploring and testing it. Postman can work from an OpenAPI description.

Can I use OpenAPI for GraphQL or gRPC?

No. OpenAPI describes HTTP APIs. GraphQL uses its own schema language and gRPC uses Protocol Buffers.

Can I test my API against the spec?

Yes. Contract-testing tools compare real responses with the description, and a monitor generated from the spec checks the live API on a schedule.