Invoer (.proto-schema)

Uitvoer (OpenAPI YAML)

Wat deze tool doet

Je hebt een Protocol Buffers-schema en een frontend-, partner- of QA-team dat een OpenAPI-document wil voor dezelfde vormen — meestal omdat de gRPC-service ook via HTTP wordt aangeboden, bijvoorbeeld via grpc-gateway. protoc-gen-openapiv2 in je build inrichten is het juiste antwoord voor productie, maar het is overkill als je gewoon snel een spec wilt delen of in een Swagger UI laden. Deze converter doet de schema-helft van het werk in je browser — plak de .proto, kopieer de YAML, en je hebt geldige OpenAPI-components.

De uitvoer is een minimaal maar geldig OpenAPI 3.1.0-document met een lege paths: {} en één entry per Protobuf-message of -enum onder components.schemas. We kiezen specifiek voor OpenAPI 3.1 omdat het datamodel aansluit bij JSON Schema 2020-12 — dat is de versie waarin formats als int64, date-time en duration first-class zijn en waarin $ref naast andere keywords mag staan zonder de oude 3.0-herschrijftrucs.

De typemapping volgt de proto3-JSON-mapping: 32-bits ints worden type: integer, format: int32, 64-bits ints worden type: string, format: int64 met een numeriek pattern (omdat JSON-getallen boven 2^53 precisie verliezen), repeated T wordt een array, map<K, V> wordt een object met additionalProperties, en veldnamen blijven snake_case zodat het schema overeenkomt met wat je server daadwerkelijk serialiseert. Enums worden uitgevoerd als type: string met een enum-lijst van waarde-namen — net als bij proto3-JSON. De converter draait volledig in je browser; niets uit je schema verlaat de pagina.

Hoe je het gebruikt

Drie stappen. De uitvoer is een YAML-document dat je in een Swagger UI kunt droppen of in een bestaand spec kunt mergen.

Plak je .proto-schema

Drop het schema in de linker editor. syntax = "proto3"; bovenaan is prima maar optioneel. De parser kan overweg met geneste message-blokken, enum-declaraties, oneof, map<K, V> en field options. import-statements tussen bestanden worden herkend maar overgeslagen — plak geïmporteerde types inline als je schema's naar elkaar verwijzen.

Veldnamen blijven in de uitvoer snake_case, in lijn met het standaardgedrag van de proto3-JSON-encoder. Als je gateway is ingesteld op camelCase JSON-namen, doe dan een zoek-en-vervang in de uitvoer of pas de gateway-instelling aan.

Lees de OpenAPI-uitvoer

Aan de rechterkant: een YAML-document met openapi: 3.1.0, een info-blok, een lege paths: {}, en je messages en enums onder components.schemas. Verwijzingen naar geneste messages gebruiken $ref: '#/components/schemas/MessageName' op de bladnaam, dus platte verwijzingen werken ook als je .proto geneste types declareert.

Sluit het aan

Drop het bestand in een Swagger UI- of Redoc-instantie om te zien hoe de schema's renderen. Voor een compleet spec voeg je echte paths-entries toe die naar je grpc-gateway-routes wijzen (of schrijf je ze met de hand) — verwijs ze met $ref naar #/components/schemas/Order en je bent klaar.

Wanneer dit echt tijd bespaart

Schema delen met een frontend- of partnerteam

Een frontendteam consumeert je gRPC-getranscodeerde service. Ze vragen om een OpenAPI-doc om in hun typegenerator of API-explorer te stoppen. Plak de .proto, kopieer de YAML, stuur het op. Zij krijgen het schema in een formaat dat hun tooling al begrijpt.

Het spec voor een nieuwe HTTP-getranscodeerde API bootstrappen

Je zet een nieuwe service op die zowel als gRPC als als HTTP draait via grpc-gateway met buf. De components/schemas-sectie is mechanisch — genereer hem met deze tool en schrijf daarna de paths met de juiste route-templates met de hand. Sneller dan alles handmatig opzetten.

Een Swagger UI in sync houden met .proto-wijzigingen

Je team gebruikt Swagger UI voor het mens-leesbare API-doc, maar de bron van de waarheid leeft in .proto-bestanden. Een backend-collega voegt shipping_address toe aan Order; je regenereert hier de schemas-sectie, plakt hem terug in het spec en publiceert de doc-update.

Sanity-check op codegen-uitvoer

Je hebt protoc-gen-openapiv2 als onderdeel van je build gedraaid en kreeg een YAML-bestand van 4000 regels. Om te verifiëren dat een specifieke message de juiste vorm heeft, plak je hier alleen dat ene .proto-bestand en vergelijk je. Snelle referentie voor hoe een schone OpenAPI 3.1-mapping eruit hoort te zien.

Veelgestelde vragen

Waarom OpenAPI 3.1 en niet 3.0?

OpenAPI 3.1 stemt zijn datamodel af op JSON Schema 2020-12, wat betekent dat formats als int64, date-time en duration goed gedefinieerd zijn en dat je $ref naast andere keywords mag plaatsen zonder de ongemakkelijke workarounds die 3.0 nodig had. De meeste moderne tooling (Redoc, Swagger UI 5, Stoplight, Spectral) gaat prima om met 3.1. Als je echt 3.0-uitvoer nodig hebt voor legacy-tooling, verander dan openapi: 3.1.0 bovenaan het document — de rest is voldoende compatibel om in de meeste gevallen nog steeds te valideren.

Waarom wordt int64 als string en niet als getal uitgevoerd?

JSON-getallen zijn in de praktijk IEEE-754 doubles — boven 2^53 verliezen ze precisie. De officiële proto3-JSON-mapping schrijft voor dat int64, uint64, fixed64, sfixed64 en sint64 als JSON-strings worden gecodeerd. Daarom gebruikt het OpenAPI-schema type: string, format: int64, pattern: "^-?[0-9]+$", om aan te sluiten op wat de server daadwerkelijk verstuurt. Als je wilt aannemen dat de waarden klein zijn en liever type: integer wilt gebruiken, doe dan een zoek-en-vervang in de uitvoer.

Waarom is paths leeg?

.proto-bestanden beschrijven messages en services, geen HTTP-routes. De HTTP-transcodering (pad, methode, query, body) wordt apart geconfigureerd — meestal via google.api.http-annotaties of grpc-gateway-opties. Die parsen we niet, dus we laten paths: {} open zodat jij het invult. Het components/schemas-deel is het herbruikbare, mechanische deel — en dat is wat deze tool je geeft.

Waarom zijn de veldnamen snake_case?

Omdat proto3-JSON ze zo standaard codeert. order_id in de .proto wordt in het JSON-wireformat geserialiseerd als "order_id", tenzij je de camelCase-optie aanzet (preserve_proto_field_names in sommige encoders, of de gateway-side flag). Door het OpenAPI-schema in snake_case te houden, sluit het aan op de JSON die je server echt verstuurt. Als je stack camelCase doet, jaag dan de uitvoer door een zoek-en-vervang.

Hoe worden geneste messages afgehandeld?

Elke Protobuf-message wordt een top-level entry onder components.schemas, geïndexeerd op zijn bladnaam (Address, niet commerce.v1.Address). Verwijzingen gebruiken $ref: '#/components/schemas/Address'. Als twee messages dezelfde bladnaam hebben in verschillende packages, overschrijft de tweede de eerste — splits ze op over aparte documenten of hernoem in de .proto.

Begrijpt de tool de google.protobuf well-known types goed?

Een paar wel. google.protobuf.Timestamp wordt type: string, format: date-time; Duration wordt type: string, format: duration; Empty wordt een leeg object; Any wordt een generiek object; Value wordt {} (elke JSON-waarde). Voor andere Google well-known types geeft de converter momenteel een $ref naar de bladnaam — die schema's kun je zelf definiëren of de verwijzingen vervangen door het juiste primitieve type.

Gerelateerde tools

Werk je met Protobuf en OpenAPI/JSON Schema, dan vullen deze elkaar mooi aan:

Protobuf naar OpenAPI Converter