Skip to main content

Understanding OpenAPI Specifications

What Is OpenAPI?​

An open API (often referred to as a public API) is a publicly available application programming interface that provides developers with programmatic access to a proprietary software application or web service.- Writing API Specification

  • API specifications can be written in YAML or JSON

    Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include:

    • Swagger Editor-- browser-based editor where you can write OpenAPI specs.
    • Swagger UI-- renders OpenAPI specs as interactive API documentation.
    • Swagger Codegen ⭐ 18k-- generates server stubs and client libraries from an OpenAPI spec.

Basic Structure​

API Server and Base Path​

Media Types​

Paths and Operations​

Describing Parameters​

Parameter Serialization​

Describing Request Body​

Describing Responses​

Data Models (Schemas)​

Adding Examples​

Authentication​

Callbacks​

Components Section​

Using $ref​

API General Info​

Grouping Operations With Tags​

OpenAPI Extensions​

OpenAPI has a way to define multiple security "schemes"

  • apiKey: an application specific key that can come from:
    • A query parameter
    • A header
    • A cookie
  • http: standard HTTP authentication systems, including:
    • bearer: a headerAuthorizationwith a value ofBearerplus a token. This is inherited from OAuth2
    • HTTP Basic authentication
    • HTTP Digest, etc
  • oauth2: all the OAuth2 ways to handle security (called "flows")
    • Several of these flows are appropriate for building an OAuth 2.0 authentication provider (like Google, Facebook, Twitter, GitHub, etc):
      • implicit
      • clientCredentials
      • authorizationCode
    • But there is one specific "flow" that can be perfectly used for handling authentication in the same application directly:
      • password: some next chapters will cover examples of this
  • openIdConnect: has a way to define how to discover OAuth2 authentication data automatically
    • This automatic discovery is what is defined in the OpenID Connect specification

Other Tools​

https://swagger.io/docs/specification/about

https://www.openapis.org

https://github.com/OAI/OpenAPI-Specification

GOTO 2019 - Introduction to OpenAPI - Lorna Jane Mitchell