uplinks:: API
tags:: #lang/en #type/term

OpenAPI

• An API specification (description format) for REST APIs
• Forrmerly known as Swagger Specification
• Used to describe
  • Available endpoints and its operations — POST /users
  • Operation parameters — Input and Output
  • Authentication methods
  • Contact information, license, ToS, etc.

Structure

• Written in YAML or JSON
• All keyword names are case-sensitive.
• Basic Structure
  • Metadata
    • Title
    • Description
    • Version — Semantic Versioning
  • Servers — API Server Base Url
  • Paths — API endpoints
    • Parameters
    • Request Body
    • Responses
  • Components — Define common data structures used in API
    • Prevent duplication
    • Reference via $ref whenever a schema is required
  • Authentication
    • HTTP Authentication — Basic, Bearer
    • API key
    • OAuth 2
    • OpenID

Why use OpenAPI ?

Tools to ease the development of APIs

• Swagger Editor — browser-based editor to help write OpenAPI specs — e.g. autocompletion
• Swagger Codegen to generate a server stub and client libraries for your API
• Swagger UIto generate interactive API documentation that kets users try out API calls in browser
• Connect to other API-related tools
  • SoapUI to create automated tests
  • Open Source Tools
  • Commercial Tools

References

• https://swagger.io/docs/specification/about/
• https://support.smartbear.com/swaggerhub/docs/tutorials/openapi-3-tutorial.html