Skip to main content

OpenAPI

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-- 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