Input (.proto-skema)

Output (OpenAPI YAML)

Hvad værktøjet gør

Du har et Protocol Buffers-skema og et frontend-, partner- eller QA-team, der gerne vil have et OpenAPI-dokument for de samme former — typisk fordi gRPC-tjenesten også er eksponeret over HTTP via noget i stil med grpc-gateway. At sætte protoc-gen-openapiv2 op i dit build er det rigtige svar i produktion, men det er overkill, når du bare har brug for et hurtigt spec til at dele eller smide i en Swagger UI. Konverteren her klarer skema-halvdelen af jobbet i din browser — indsæt .proto'en, kopiér YAML'en, og du har gyldige OpenAPI-components.

Outputtet er et minimalt, men gyldigt OpenAPI 3.1.0-dokument med et tomt paths: {} og én post pr. Protobuf-message eller -enum under components.schemas. Vi vælger specifikt OpenAPI 3.1, fordi datamodellen flugter med JSON Schema 2020-12 — det er versionen, hvor formater som int64, date-time og duration er førsteklasses, og hvor $ref kan stå ved siden af andre nøgleord uden de gamle 3.0-omskrivningsfusk.

Typemappingen følger proto3-JSON-mappingen: 32-bit-heltal bliver til type: integer, format: int32, 64-bit-heltal bliver til type: string, format: int64 med et numerisk pattern (fordi JSON-tal over 2^53 mister præcision), repeated T bliver til et array, map<K, V> bliver til et objekt med additionalProperties, og feltnavnene forbliver i snake_case, så skemaet matcher det, din server faktisk serialiserer. Enums sendes ud som type: string med en enum-liste over værdienavne — som i proto3-JSON. Konverteren kører helt i din browser; intet fra dit skema forlader siden.

Sådan bruger du den

Tre trin. Outputtet er et YAML-dokument, du kan smide ind i en Swagger UI eller flette ind i et eksisterende spec.

Indsæt dit .proto-skema

Smid skemaet ind i editoren til venstre. syntax = "proto3"; i toppen er fint, men valgfrit. Parseren håndterer indlejrede message-blokke, enum-deklarationer, oneof, map<K, V> og feltoptioner. import-statements på tværs af filer genkendes, men springes over — indsæt importerede typer inline, hvis dine skemaer refererer hinanden.

Feltnavnene forbliver snake_case i outputtet, hvilket matcher standardopførslen for proto3-JSON-encoderen. Hvis din gateway er sat op til camelCase-JSON-navne, så kør en søg-og-erstat i outputtet eller skift gateway-indstillingen.

Læs OpenAPI-outputtet

Til højre: et YAML-dokument med openapi: 3.1.0, en info-blok, et tomt paths: {} og dine messages og enums under components.schemas. Referencer til indlejrede messages bruger $ref: '#/components/schemas/MessageName' mod bladnavnet, så flade referencer virker, selv når din .proto erklærer indlejrede typer.

Kobl det sammen

Smid filen ind i en Swagger UI- eller Redoc-instans for at se, hvordan skemaerne renderes. For at gøre det til et komplet spec tilføjer du rigtige paths-poster, der peger på dine grpc-gateway-ruter (eller skriver dem i hånden) — referér dem med $ref mod #/components/schemas/Order, og du er færdig.

Hvornår det reelt sparer tid

Dele et skema med et frontend- eller partnerteam

Et frontendteam forbruger din gRPC-transkodede tjeneste. De har bedt om et OpenAPI-doc, de kan stoppe ind i deres typegenerator eller API-explorer. Indsæt .proto'en, kopiér YAML'en, send afsted. De får skemaet i et format, deres tooling allerede forstår.

Bootstrappe specet for et nyt HTTP-transkodet API

Du sætter en ny tjeneste op, der skal køre både som gRPC og HTTP via grpc-gateway med buf. components/schemas-sektionen er mekanisk — generér den med dette værktøj og skriv så paths i hånden med de rigtige ruteskabeloner. Hurtigere end at bygge det hele fra bunden.

Holde en Swagger UI synkroniseret med ændringer i .proto

Dit team bruger Swagger UI til den menneskelæsbare API-doc, men sandheden bor i .proto-filerne. En backendkollega tilføjer shipping_address til Order; du regenererer schemas-sektionen her, klistrer den tilbage i specet og udsender doc-opdateringen.

Sanity-tjekke codegen-output

Du har kørt protoc-gen-openapiv2 som en del af dit build og fået en YAML-fil på 4000 linjer. For at verificere, at en bestemt message har den rigtige form, indsætter du bare den ene .proto-fil her og sammenligner. Hurtig reference til, hvordan en pæn OpenAPI 3.1-mapping bør se ud.

Almindelige spørgsmål

Hvorfor OpenAPI 3.1 og ikke 3.0?

OpenAPI 3.1 retter sin datamodel ind efter JSON Schema 2020-12, hvilket betyder, at formater som int64, date-time og duration er veldefinerede, og at du kan have $ref ved siden af andre nøgleord uden de akavede workarounds, 3.0 krævede. Det meste moderne tooling (Redoc, Swagger UI 5, Stoplight, Spectral) taler 3.1 fint. Hvis du virkelig har brug for 3.0-output til legacy-tooling, så skift openapi: 3.1.0 i toppen af dokumentet — resten er kompatibel nok til, at det som regel stadig validerer.

Hvorfor sendes int64 ud som string og ikke tal?

JSON-tal er i praksis IEEE-754-doubles — de mister præcision over 2^53. Den officielle proto3-JSON-mapping kræver, at int64, uint64, fixed64, sfixed64 og sint64 kodes som JSON-strings. Derfor bruger OpenAPI-skemaet type: string, format: int64, pattern: "^-?[0-9]+$" for at matche det, serveren rent faktisk sender. Hvis du vil antage små værdier og bruge type: integer i stedet, så kør en søg-og-erstat i outputtet.

Hvorfor er paths tomt?

.proto-filer beskriver messages og services, ikke HTTP-ruter. HTTP-transkodningen (path, method, query, body) konfigureres separat — typisk via google.api.http-annoteringer eller grpc-gateway-optioner. Dem parser vi ikke, så vi lader paths: {} stå tomt, så du kan udfylde det. components/schemas-delen er den genbrugelige, mekaniske halvdel — og det er det, værktøjet her giver dig.

Hvorfor er feltnavnene i snake_case?

Fordi det er sådan, proto3-JSON koder dem som standard. order_id i .proto'en serialiseres til "order_id" i JSON-wireformatet, medmindre du tænder for camelCase-optionen (preserve_proto_field_names i nogle encoders, eller gateway-flaget). At holde OpenAPI-skemaet i snake_case betyder, at det matcher den JSON, din server reelt sender. Hvis din stack kører camelCase, så send outputtet gennem en søg-og-erstat.

Hvordan håndteres indlejrede messages?

Hver Protobuf-message bliver til en topniveau-post under components.schemas indekseret efter sit bladnavn (Address, ikke commerce.v1.Address). Referencer bruger $ref: '#/components/schemas/Address'. Hvis to messages har samme bladnavn i forskellige pakker, overskriver den anden den første — del dem op i separate dokumenter, eller omdøb i .proto.

Forstår den google.protobuf well-known types ordentligt?

Et par af dem. google.protobuf.Timestamp renderes som type: string, format: date-time; Duration som type: string, format: duration; Empty som et tomt objekt; Any som et generisk objekt; Value som {} (en vilkårlig JSON-værdi). For andre Google well-known types sender konverteren i øjeblikket et $ref til bladnavnet — du kan enten definere de skemaer selv eller erstatte referencerne med den rigtige primitive type.

Relaterede værktøjer

Hvis du roder med Protobuf og OpenAPI/JSON Schema, så går disse godt i spand:

Protobuf til OpenAPI-konverter