Sim Dev, a documentação pode ser sua amiga!

É tarefa cotidiana no mundo dev fazer junções entre as partes, e para isso seguimos acordos da tecnologia usada, assim quando uma comunicação REST dá sucesso devolvemos um 200, o que sistemas está nos dizendo é::

"Legal, tudo bem aqui do meu lado, agora é que você"

sequenceDiagram
    participant frontend
    participant backend
    frontend->>backend: Salva esse dado pra mim?
    backend->>frontend: 200

Esse 200 não está lá por acaso, ele é um acordo previo, e se voce é DEV deveria conhecer bem:
Descrição do Codigos Http

Mas muitas vezes precisamos de uma acordo mais extensivo e vamos criando casos usando o bom e velho 'boca-à-boca', embora comunicação entre os times seja importantes E SEMPRE BOM LEMBRAR DA MAXIMA:

Palavras o vento leva.

Assim, precisamos de uma maneira de combinar o formato dos dados enviados, bem com as respostas e os casos de erros.

vamos aqui imaginar um cenário aqui:

Precisamos enviar um dado para o backend, explicar o formato do dado e os codigos http e as respostas de erro:
Então vamos, Siga-me os bons:

o nosso record deve ser parecer com uma coisa assim:

{
    "id": "0123",
    "name": "Artigo do swagger",
    "createdAt": "17:55:01 30/11/2022" 
    "status": "published"
}

E vamos enviar dados assim:

4. POST /record/save

# VERSÃO QUE O ARQUIVO FOI ESCRITO
openapi: 3.0.3

# INFORMAÇÕES GERAIS
info:
  title: Artigo do Alexandre no TabNews
  version: 1.0.0
  
# REPRESENTAÇÃO DO NOSSO OBJETO
tags:
  - name: record
    description: represent a RECORD

# ROTAS QUE VAMOS TRABALHAR
paths:
  /record/save:
    post:
      tags:
        - record
      summary: Create a new record
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Record'
        required: true
      # AS POSSIVEIS REPOSTAS E AS MENSAGENS 
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid ID supplied
        '405':
          description: Bad Request
          
# NOSSO OBJETO DESCRITO
components:
  schemas:
    Record:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          format: String
          example: Defalt Record
        createdAt:
          type: string
          format: date-time
          example:  19:27:00  30/11/2022 
        status:
          type: string
          description: Order Status
          example: approved
          enum:
            - placed
            - approved
            - delivered

isso descreve bastante coisa, e vamos nos aprofundar em cada Etapa.

1. Aqui temos a apresentação do nosso arquivo, são os bons costumes, não são coisas obrigatorias, mas são de bom tom. diria até que são boa educação.

• PS. Sempre escreva pelo menos a versão do arquivo.

# VERSÃO QUE O ARQUIVO FOI ESCRITO
openapi: 3.0.3

# INFORMAÇÕES GERAIS
info:
  title: Artigo do Alexandre no TabNews
  version: 1.0.0

2. Aqui vamos saber o escopo basico dos objetos que vamos trabalhar,

# REPRESENTAÇÃO DO NOSSO OBJETO
tags:
  - name: record
    description: represent a RECORD

3. é aqui a parte que mais necessita de carinho e atenção, onde descrevemos as repostas possiveis, e os casos de erros, assim o cliente pode saber qual atititude deve tomar.

# ROTAS QUE VAMOS TRABALHAR
paths:
  /record:
    post:
      tags:
        - record
      summary: Create a new record
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Record'
        required: true
      # AS POSSIVEIS REPOSTAS E AS MENSAGENS 
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid ID supplied
        '405':
          description: Name out of pattern

Aqui vamos considerar:

1. se esse cara retornar um 200 é sinal que tudo está bem e a vida pode continuar.

2. se ele retornar um codigo 400 é sinal que formatamos mal nosso objeto, e vamos precisar rever o nosso POST. aqui o declaração do REST 400: https://developer.mozilla.org/pt-BR/docs/Web/HTTP/Status/400

3. se ele retonar um 405, é bem possivel que embora o dado esteja correto estamos usando o verbo errado, talvez enviando via PUT e ele só pode aceitar POST,

bem dev por hoje é isso, existem muitas outras coisas maravilosas para expandir, mas vamos em doses pequenas, por hoje se quiser fazer a lição de casa, import esse swagger aqui:

https://editor.swagger.io/

e se divirta praticando com os seus dados.