Documentação e OpenAPI

import swagger from "@fastify/swagger";
import Fastify from "fastify";

const app = Fastify();
await app.register(swagger, {
  openapi: { openapi: "3.1.0", info: { title: "API de Pedidos", version: "1.0.0" } },
});

// Os esquemas validam a entrada, formatam a saída e viram a documentação
const Pedido = {
  type: "object",
  required: ["id", "cliente_id", "status", "total", "criado_em"],
  properties: {
    id: { type: "integer" },
    cliente_id: { type: "integer" },
    status: { type: "string", enum: ["aberto", "pago", "enviado"] },
    total: { type: "string", pattern: "^[0-9]+\\.[0-9]{2}$", description: "Valor em reais" },
    criado_em: { type: "string", format: "date-time" },
  },
} as const;

const NovoPedido = {
  type: "object",
  required: ["cliente_id", "total"],
  additionalProperties: false,
  properties: {
    cliente_id: { type: "integer", minimum: 1 },
    total: Pedido.properties.total,
  },
} as const;

const Problema = {
  type: "object",
  properties: { title: { type: "string" }, status: { type: "integer" } },
} as const;

type Pedido = { id: number; cliente_id: number; status: string; total: string; criado_em: string };
const pedidos = new Map<number, Pedido>();

app.get<{ Params: { id: number } }>("/pedidos/:id", {
  schema: {
    operationId: "buscarPedido",
    params: { type: "object", properties: { id: { type: "integer", minimum: 1 } } },
    response: { 200: Pedido, 404: Problema },
  },
}, async (req, reply) => {
  const pedido = pedidos.get(req.params.id);
  if (!pedido) return reply.code(404).type("application/problem+json")
    .send({ title: "Pedido não encontrado", status: 404 });
  return pedido;
});

app.post<{ Body: { cliente_id: number; total: string } }>("/pedidos", {
  schema: { operationId: "criarPedido", body: NovoPedido, response: { 201: Pedido } },
}, async (req, reply) => {
  const pedido = {
    id: pedidos.size + 1,
    ...req.body,
    status: "aberto",
    criado_em: new Date().toISOString(),
  };
  pedidos.set(pedido.id, pedido);
  return reply.code(201).send(pedido);
});

app.get("/openapi.json", { schema: { hide: true } }, async () => app.swagger());

await app.listen({ port: 3000, host: "0.0.0.0" });
console.log("ouvindo");

from datetime import datetime, timezone
from decimal import Decimal
from enum import Enum

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="API de Pedidos", version="1.0.0")


class Status(str, Enum):
    aberto = "aberto"
    pago = "pago"
    enviado = "enviado"


class NovoPedido(BaseModel):
    cliente_id: int = Field(gt=0)
    total: Decimal = Field(gt=0, description="Valor em reais")


class Pedido(BaseModel):
    id: int
    cliente_id: int
    status: Status
    total: Decimal
    criado_em: datetime


pedidos: dict[int, Pedido] = {}


@app.get("/pedidos/{id}", responses={404: {"description": "Pedido não encontrado"}})
def buscar(id: int) -> Pedido:
    if id not in pedidos:
        raise HTTPException(404, "Pedido não encontrado")
    return pedidos[id]


@app.post("/pedidos", status_code=201)
def criar(novo: NovoPedido) -> Pedido:
    pedido = Pedido(id=len(pedidos) + 1, cliente_id=novo.cliente_id, status=Status.aberto,
                    total=novo.total, criado_em=datetime.now(timezone.utc))
    pedidos[pedido.id] = pedido
    return pedido

package main

import (
	"context"
	"fmt"
	"net/http"
	"sync"
	"time"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humago"
)

type Pedido struct {
	ID        int       `json:"id"`
	ClienteID int       `json:"cliente_id"`
	Status    string    `json:"status" enum:"aberto,pago,enviado"`
	Total     string    `json:"total" pattern:"^[0-9]+\\.[0-9]{2}$" doc:"Valor em reais"`
	CriadoEm  time.Time `json:"criado_em"`
}

type BuscarEntrada struct {
	ID int `path:"id" minimum:"1"`
}

type CriarEntrada struct {
	Body struct {
		ClienteID int    `json:"cliente_id" minimum:"1"`
		Total     string `json:"total" pattern:"^[0-9]+\\.[0-9]{2}$" doc:"Valor em reais"`
	}
}

type PedidoSaida struct {
	Body Pedido
}

func main() {
	var (
		mu      sync.Mutex
		pedidos = map[int]Pedido{}
	)
	mux := http.NewServeMux()
	api := humago.New(mux, huma.DefaultConfig("API de Pedidos", "1.0.0")) // publica /openapi.json

	huma.Register(api, huma.Operation{
		OperationID: "buscarPedido", Method: http.MethodGet, Path: "/pedidos/{id}",
		Errors: []int{404},
	}, func(ctx context.Context, e *BuscarEntrada) (*PedidoSaida, error) {
		mu.Lock()
		defer mu.Unlock()
		p, ok := pedidos[e.ID]
		if !ok {
			return nil, huma.Error404NotFound("Pedido não encontrado")
		}
		return &PedidoSaida{Body: p}, nil
	})

	huma.Register(api, huma.Operation{
		OperationID: "criarPedido", Method: http.MethodPost, Path: "/pedidos",
		DefaultStatus: http.StatusCreated,
	}, func(ctx context.Context, e *CriarEntrada) (*PedidoSaida, error) {
		mu.Lock()
		defer mu.Unlock()
		p := Pedido{ID: len(pedidos) + 1, ClienteID: e.Body.ClienteID, Status: "aberto",
			Total: e.Body.Total, CriadoEm: time.Now().UTC()}
		pedidos[p.ID] = p
		return &PedidoSaida{Body: p}, nil
	})

	fmt.Println("ouvindo")
	http.ListenAndServe(":3000", mux)
}

package pedidos;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Pattern;
import java.time.OffsetDateTime;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
@RestController
public class App {
    enum Status { aberto, pago, enviado }

    record NovoPedido(
        @JsonProperty("cliente_id") @NotNull @Min(1) Integer clienteId,
        @NotNull @Pattern(regexp = "^[0-9]+\\.[0-9]{2}$")
        @Schema(description = "Valor em reais") String total) {}

    record Pedido(
        int id,
        @JsonProperty("cliente_id") int clienteId,
        Status status,
        String total,
        @JsonProperty("criado_em") OffsetDateTime criadoEm) {}

    private final Map<Integer, Pedido> pedidos = new ConcurrentHashMap<>();

    @GetMapping("/pedidos/{id}")
    @Operation(operationId = "buscarPedido")
    @ApiResponse(responseCode = "200", description = "O pedido")
    @ApiResponse(responseCode = "404", description = "Pedido não encontrado")
    public ResponseEntity<Pedido> buscar(@PathVariable @Min(1) int id) {
        var pedido = pedidos.get(id);
        return pedido == null ? ResponseEntity.notFound().build() : ResponseEntity.ok(pedido);
    }

    @PostMapping("/pedidos")
    @ResponseStatus(HttpStatus.CREATED)
    @Operation(operationId = "criarPedido")
    public Pedido criar(@Valid @RequestBody NovoPedido novo) {
        var pedido = new Pedido(pedidos.size() + 1, novo.clienteId(), Status.aberto,
            novo.total(), OffsetDateTime.now());
        pedidos.put(pedido.id(), pedido);
        return pedido;
    }

    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

using Microsoft.AspNetCore.Http.HttpResults;
using System.Collections.Concurrent;
using System.ComponentModel.DataAnnotations;
using System.Text.Json.Serialization;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi(); // gera o documento a partir das rotas
builder.Services.ConfigureHttpJsonOptions(o =>
    o.SerializerOptions.Converters.Add(new JsonStringEnumConverter()));
var app = builder.Build();
app.MapOpenApi(); // publica em /openapi/v1.json

var pedidos = new ConcurrentDictionary<int, Pedido>();

app.MapGet("/pedidos/{id}", Results<Ok<Pedido>, NotFound> (int id) =>
        pedidos.TryGetValue(id, out var p) ? TypedResults.Ok(p) : TypedResults.NotFound())
    .WithName("buscarPedido");

app.MapPost("/pedidos", (NovoPedido novo) =>
    {
        var p = new Pedido(pedidos.Count + 1, novo.ClienteId, Status.Aberto, novo.Total,
            DateTimeOffset.UtcNow);
        pedidos[p.Id] = p;
        return TypedResults.Created($"/pedidos/{p.Id}", p);
    })
    .WithName("criarPedido");

app.Run("http://0.0.0.0:3000");

enum Status { Aberto, Pago, Enviado }
record NovoPedido(
    [property: Range(1, int.MaxValue)] int ClienteId,
    [property: Range(0.01, double.MaxValue)] decimal Total);
record Pedido(int Id, int ClienteId, Status Status, decimal Total, DateTimeOffset CriadoEm);