Indata (.proto-schema)

Utdata (OpenAPI YAML)

Vad det här verktyget gör

Du har ett Protocol Buffers-schema och ett frontend-, partner- eller QA-team som vill ha ett OpenAPI-dokument för samma former — oftast för att gRPC-tjänsten också är exponerad över HTTP via något som grpc-gateway. Att sätta upp protoc-gen-openapiv2 i bygget är rätt svar för produktion, men det är överkill när du bara vill ha en snabb spec att dela eller dra in i en Swagger UI. Den här konverteraren gör schema-halvan av jobbet i din webbläsare — klistra in .proto, kopiera YAML:en, så har du giltiga OpenAPI-components.

Utdatan är ett minimalt men giltigt OpenAPI 3.1.0-dokument med ett tomt paths: {} och en post per Protobuf-meddelande eller -enum under components.schemas. Vi väljer specifikt OpenAPI 3.1 för att datamodellen ligger i linje med JSON Schema 2020-12 — det är versionen där format som int64, date-time och duration är förstklassiga och där $ref får stå bredvid andra nyckelord utan de gamla 3.0-omskrivningstricken.

Typmappingen följer proto3-JSON-mappingen: 32-bitars heltal blir type: integer, format: int32, 64-bitars heltal blir type: string, format: int64 med ett numeriskt pattern (för att JSON-tal över 2^53 tappar precision), repeated T blir en array, map<K, V> blir ett objekt med additionalProperties, och fältnamnen är kvar i snake_case så att schemat matchar det din server faktiskt serialiserar. Enums skickas ut som type: string med en enum-lista över värdenamn — precis som i proto3-JSON. Konverteraren körs helt och hållet i din webbläsare; inget från schemat lämnar sidan.

Så använder du det

Tre steg. Utdatan är ett YAML-dokument du kan dumpa in i en Swagger UI eller mergea in i ett befintligt spec.

Klistra in ditt .proto-schema

Släpp schemat i den vänstra editorn. syntax = "proto3"; högst upp är OK men frivilligt. Parsern hanterar nästade message-block, enum-deklarationer, oneof, map<K, V> och fältoptioner. import-satser mellan filer känns igen men hoppas över — klistra in importerade typer inline om dina scheman refererar varandra.

Fältnamnen är kvar i snake_case i utdatan, vilket matchar proto3-JSON-encoderns standardbeteende. Är din gateway konfigurerad för camelCase-JSON-namn så kör en sök-och-ersätt i utdatan eller ändra gateway-inställningen.

Läs OpenAPI-utdatan

Till höger: ett YAML-dokument med openapi: 3.1.0, ett info-block, ett tomt paths: {} och dina meddelanden och enums under components.schemas. Referenser till nästade meddelanden använder $ref: '#/components/schemas/MessageName' mot lövnamnet, så platta referenser fungerar även när din .proto deklarerar nästade typer.

Koppla ihop det

Släpp filen i en Swagger UI- eller Redoc-instans för att se hur schemana renderas. För att göra det till ett komplett spec lägger du till riktiga paths-poster som pekar på dina grpc-gateway-rutter (eller skriver dem för hand) — referera dem med $ref mot #/components/schemas/Order, så är det klart.

När det faktiskt sparar tid

Dela ett schema med ett frontend- eller partnerteam

Ett frontendteam konsumerar din gRPC-transkodade tjänst. De har bett om ett OpenAPI-doc för att kunna stoppa in det i sin typgenerator eller API-explorer. Klistra in .proto, kopiera YAML:en, skicka över. De får schemat i ett format som deras tooling redan förstår.

Bootstrappa specet för ett nytt HTTP-transkodat API

Du sätter upp en ny tjänst som ska köras både som gRPC och HTTP via grpc-gateway med buf. components/schemas-sektionen är mekanisk — generera den med det här verktyget och skriv sedan paths för hand med rätt rutmallar. Snabbare än att bygga upp allt manuellt.

Hålla en Swagger UI synkad med ändringar i .proto

Ditt team använder Swagger UI för det människoläsbara API-doccet, men sanningskällan bor i .proto-filer. En backendkollega lägger till shipping_address i Order; du regenererar schemas-sektionen här, klistrar in den i specet igen och skickar ut doc-uppdateringen.

Sanity-kolla codegen-utdata

Du körde protoc-gen-openapiv2 som en del av bygget och fick en YAML-fil på 4000 rader. För att verifiera att ett specifikt meddelande har rätt form klistrar du bara in den enskilda .proto-filen här och jämför. Snabb referens för hur en städad OpenAPI 3.1-mapping ska se ut.

Vanliga frågor

Varför OpenAPI 3.1 och inte 3.0?

OpenAPI 3.1 lägger sin datamodell i linje med JSON Schema 2020-12, vilket innebär att format som int64, date-time och duration är välspecificerade och att du kan ha $ref bredvid andra nyckelord utan de klumpiga workarounds som 3.0 krävde. De flesta moderna verktyg (Redoc, Swagger UI 5, Stoplight, Spectral) hanterar 3.1 utan problem. Om du på riktigt behöver 3.0-utdata för legacy-tooling så ändrar du openapi: 3.1.0 högst upp i dokumentet — resten är tillräckligt kompatibel för att oftast ändå validera.

Varför skickas int64 ut som sträng och inte ett tal?

JSON-tal är i praktiken IEEE-754-doubles — de tappar precision över 2^53. Den officiella proto3-JSON-mappingen säger att int64, uint64, fixed64, sfixed64 och sint64 ska kodas som JSON-strängar. Därför använder OpenAPI-schemat type: string, format: int64, pattern: "^-?[0-9]+$" för att matcha det servern faktiskt skickar. Om du vill anta små värden och använda type: integer i stället så kör en sök-och-ersätt i utdatan.

Varför är paths tomt?

.proto-filer beskriver meddelanden och tjänster, inte HTTP-rutter. HTTP-transkodningen (path, method, query, body) konfigureras separat — oftast via google.api.http-annoteringar eller grpc-gateway-options. Vi parsar inte dem, så vi lämnar paths: {} till dig att fylla i. components/schemas-delen är den återanvändbara, mekaniska halvan — och det är det här verktyget ger dig.

Varför är fältnamnen i snake_case?

För att det är så proto3-JSON kodar dem som standard. order_id i .proto:n serialiseras till "order_id" i JSON-wireformatet, om du inte slår på camelCase-optionen (preserve_proto_field_names i vissa encoders, eller flaggan på gateway-sidan). Att hålla OpenAPI-schemat i snake_case innebär att det matchar den JSON som din server faktiskt skickar. Om din stack kör camelCase så låter du utdatan gå genom en sök-och-ersätt.

Hur hanteras nästade meddelanden?

Varje Protobuf-meddelande blir en topp-nivå-post under components.schemas nycklad på sitt lövnamn (Address, inte commerce.v1.Address). Referenser använder $ref: '#/components/schemas/Address'. Om två meddelanden har samma lövnamn i olika paket så skriver det andra över det första — dela upp dem på separata dokument eller döp om i .proto.

Förstår den google.protobuf well-known types ordentligt?

Några av dem. google.protobuf.Timestamp renderas som type: string, format: date-time; Duration som type: string, format: duration; Empty som ett tomt objekt; Any som ett generiskt objekt; Value som {} (vilket JSON-värde som helst). För andra Google well-known types skickar konverteraren just nu ut ett $ref till lövnamnet — du kan antingen definiera de schemana själv eller byta ut referenserna mot rätt primitiv typ.

Relaterade verktyg

Om du sliter med Protobuf och OpenAPI/JSON Schema så passar de här ihop bra:

Protobuf till OpenAPI-konverterare