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
-
Basic
-
Bearer
-
other HTTP schemes as defined by RFC 7235 and HTTP Authentication Scheme Registry
-
API keys in headers, query string or cookies
-
Cookie Authentication
-
OAuth 2.0
-
OpenID Connect Discovery
Links
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
- Several of these flows are appropriate for building an OAuth 2.0 authentication provider (like Google, Facebook, Twitter, GitHub, etc):
- 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
- Apiary
- OpenAPI
- API Blueprint
- Spotlight Studio
- Spectral - api validation
- https://github.com/apideck-libraries/portman
https://swagger.io/docs/specification/about