OpenAPI Contracts

The OpenAPI Specification is an API description format for REST APIs. It is the successor of Swagger Specification.
The specification contains:

Description
Authentication information
Endpoints (like /tasks) and operations (HTTP verbs like GET, POST..)
Optionally additional information like contact, licensing, terms of use and more

Versions

The current version is 3 and can be found on GitHub: OpenAPI-Specification version list

Formats

The OpenAPI Specification usually is written in YAML, but sometimes also the JSON-format is used. Both variants enable a format that can be read by both humans and machines.

Contract First development

In the wild, one often sees the approach that the server is implemented first and the contract is generated from it - for example with an OpenAPI middleware.
This often results in APIs that do not follow the REST standard and often delays the development of clients, since they have to constantly wait for the further development of the server. Likewise, breaking changes are a big problem with a server-implementation-first approach.
This is not recommended.

It is generally advisable to develop the contract first and then implement it.
This approach is considered the more stable variant in the development process and ensures long-term planning, so that the risks of breaking the API are reduced.

Sample

openapi: "3.0.0"
info:
  title: Task API
  description: This is a sample server for tasks
  termsOfService: https://dotnet.rest/terms/
  contact:
    name: API Support
    url: https://www.dotnet.rest/support
    email: [email protected]
  license:
    name: MIT
    url: dotnet.rest
  version: 1.0.1
servers:
  - url: https://api.dotnet.rest/v1
    description: Task API V1
  - url: https://api.dotnet.rest/latest
    description: Task API latest
  - url: https://dev-api.dotnet.rest/v2
    description: Task API v2 DEV
paths:
  /tasks:
    get:
      summary: "Gets all your tasks"
      operationId: "getAllTasks"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema: 
                type: "array"
                items: 
                  $ref: "#/components/schemas/TaskModel"
    post:
      summary: "Gets all your tasks"
      operationId: "addTasks"
      requestBody:
        description: "Task create model"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateModel'
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema: 
                type: "array"
                items: 
                  $ref: "#/components/schemas/TaskModel"
                  
  /tasks/{id}:
    get:
      summary: "Gets all your tasks"
      operationId: "getTask"
      parameters:
        - name: id
          description: Id of task
          in: path
          required: true
          schema:
            type: "integer"
            format: "int32"
      responses:
        "200":
          description: "task found and returned"
          content:
            application/json:
              schema:
                  $ref: "#/components/schemas/TaskModel"
        "404":
          description: "task not found by given Id"
                  
                  
components:
  schemas:
    TaskModel:
      type: "object"
      properties:
        id:
          type: "integer"
          format: "int32"
        title:
          type: "string"
        isDone:
          type: "boolean"
    TaskCreateModel:
      type: "object"
      properties:
        id:
          type: "integer"
          format: "int32"
        title:
          type: "string"
        isDone:
          type: "boolean"

OpenAPI Homepage

Last modified February 27, 2024: Merge pull request #7 from BenjaminAbt/feature/why-rest (4b3c4d0)