What is a .proto file and how does gRPC code generation work, and why is contract-first stronger than OpenAPI/Swagger?

syntax = "proto3";

package com.bank;

option java_package = "com.bank.proto";
option java_outer_classname = "BankProtos";

message TransferRequest {
    string from_account = 1;   // field number 1
    string to_account = 2;     // field number 2
    string amount = 3;         // BigDecimal as string
    string idempotency_key = 4;
}

message TransferResponse {
    string reference_id = 1;
    string status = 2;
    string message = 3;
}

service AccountService {
    rpc Transfer (TransferRequest) returns (TransferResponse);
    rpc GetBalance (BalanceRequest) returns (BalanceResponse);
    rpc StreamPrices (PriceRequest) returns (stream PriceUpdate);
}

message BalanceRequest {
    string account_id = 1;
}

message BalanceResponse {
    string account_id = 1;
    string balance = 2;
}

message PriceRequest {
    string symbol = 1;
}

message PriceUpdate {
    string symbol = 1;
    string price = 2;
    int64 timestamp = 3;
}

# Using the protobuf Maven plugin
mvn protobuf:compile protobuf:compile-custom

# Generated files:
# target/generated-sources/protobuf/java/com/bank/proto/BankProtos.java
# target/generated-sources/protobuf/grpc-java/com/bank/proto/AccountServiceGrpc.java

package com.bank.service;

import com.bank.proto.AccountServiceGrpc;
import com.bank.proto.BankProtos.*;
import io.grpc.stub.StreamObserver;
import java.math.BigDecimal;
import java.util.UUID;

public class AccountServiceImpl
        extends AccountServiceGrpc.AccountServiceImplBase {

    @Override
    public void transfer(TransferRequest request,
                          StreamObserver<TransferResponse> responseObserver) {
        BigDecimal amount = new BigDecimal(request.getAmount());
        String refId = UUID.randomUUID().toString();

        System.out.println("Transfer " + amount
                + " from " + request.getFromAccount()
                + " to " + request.getToAccount());

        TransferResponse response = TransferResponse.newBuilder()
                .setReferenceId(refId)
                .setStatus("COMPLETED")
                .setMessage("Transfer successful")
                .build();

        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }
}

package com.bank.client;

import com.bank.proto.AccountServiceGrpc;
import com.bank.proto.BankProtos.*;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import java.math.BigDecimal;

public class TransferClient {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
                .forAddress("localhost", 9090)
                .usePlaintext()
                .build();

        // Blocking stub: feels like a local method call
        AccountServiceGrpc.AccountServiceBlockingStub stub =
                AccountServiceGrpc.newBlockingStub(channel);

        TransferRequest request = TransferRequest.newBuilder()
                .setFromAccount("SAV2001")
                .setToAccount("SAV2002")
                .setAmount("50000.00")
                .setIdempotencyKey("txn-" + System.currentTimeMillis())
                .build();

        TransferResponse response = stub.transfer(request);
        System.out.println("Transfer: " + response.getStatus()
                + " ref=" + response.getReferenceId());

        channel.shutdown();
    }
}

Transfer: COMPLETED ref=a1b2c3d4-5678-...

// Version 1:
message Account {
    string id = 1;
    string balance = 2;
}

// Version 2 (compatible): renamed 'balance' to 'current_balance'
message Account {
    string id = 1;
    string current_balance = 2;  // same number, new name: wire-compatible
}

// Version 3 (compatible): added a new field
message Account {
    string id = 1;
    string current_balance = 2;
    string currency = 3;  // new field, old clients ignore it
}

// Protocol Buffers: if someone removes 'amount' from the .proto,
// the client code that calls getAmount() won't even compile.
// Compile-time enforcement.

// OpenAPI: if someone removes 'amount' from the JSON response,
// the client discovers it at runtime when parsing fails.
// Runtime surprise.

service TradingService {
    // Unary: one request, one response
    rpc GetBalance (BalanceRequest) returns (BalanceResponse);

    // Server streaming: one request, many responses
    rpc StreamPrices (PriceRequest) returns (stream PriceUpdate);

    // Client streaming: many requests, one response
    rpc UploadTransactions (stream Transaction) returns (UploadSummary);

    // Bidirectional streaming: many requests, many responses
    rpc TradeSession (stream Order) returns (stream Fill);
}

message Account {
    reserved 5, 6;         // never reuse these field numbers
    reserved "old_field";  // never reuse this field name

    string id = 1;
    string balance = 2;
}