Do you create JSON schemas, use OpenAPI, Swagger to describe APIs?

Yes, JSON schemas, OpenAPI, and Swagger are often used to describe APIs. JSON schemas help formalize the data structure transmitted through APIs, which facilitates validation and documentation generation.

OpenAPI (formerly Swagger) is a specification for describing RESTful APIs, allowing for clear documentation, client and server SDK generation, and API testing. For example, OpenAPI can describe all endpoints, methods, parameters, and data models.

An example of a simple OpenAPI description:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get list of users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string