google / google/gnostic

OneOf support in OpenAPIv3

Open
#251 27 comments 5 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2.3k
Forks
279
PR merge metrics
No merged PRs in 30d

Description

Hello there!
Thanks for the magical tool! It took a while to get my head around but it is great!

I was testing out the capability of the proto ->OpenAPIV3 and it works nicely.
However I noticed that it doesn't use the latest `oneOf` [keywords](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/) to annotate a `oneof` type in the proto message.

For example given this proto file:

```proto
syntax = "proto3";

package twirp.example.haberdasher;

import "google/api/annotations.proto";
option go_package="twirp/example/haberdasher";

// Haberdasher service makes hats for clients.
service Haberdasher {
// MakeHat produces a hat of mysterious, randomly-selected color!
rpc MakeHat(Size) returns (Hat) {
option(google.api.http) = {
post: "/v1/create"
body: "text"
};
};
}

// Size of a Hat, in inches.
message Size {
int32 inches = 1; // must be > 0
}

// A Hat is a piece of headwear made by a Haberdasher.
message Hat {
int32 inches = 1;
string color = 2; // anything but "invisible"
string name = 3; // i.e. "bowler"
oneof type {
Type1 type1 = 4;
Type1 type2 = 5;
}
}

message Type1 {
string id = 1;
}

message Type2 {
string id = 1;
}
```

I get this:

```yaml
# Generated with protoc-gen-openapi
# https://github.com/googleapis/gnostic/tree/master/apps/protoc-gen-openapi

openapi: 3.0.3
info:
title: Haberdasher
description: Haberdasher service makes hats for clients.
version: 0.0.1
paths:
/v1/create:
post:
summary: MakeHat produces a hat of mysterious, randomly-selected color!
operationId: Haberdasher_MakeHat
parameters:
- name: inches
in: query
schema:
type: string
requestBody:
content:
application/json: {}
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Hat'
components:
schemas:
Hat:
properties:
inches:
type: integer
format: int32
color:
type: string
name:
type: string
type1:
$ref: '#/components/schemas/Type1'
type2:
$ref: '#/components/schemas/Type2'
description: A Hat is a piece of headwear made by a Haberdasher.
Type1:
properties:
id:
type: string
Type2:
properties:
id:
type: string

```

note the `type1` and `type2` fields are flat in the schema instead of being something like:

```
type:
oneOf:
- $ref: '#/components/schemas/Type1'
- $ref: '#/components/schemas/Type2'
```

Maybe I'm missing something?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.