Generate Swagger documentation

[maksadbek]

Hello,

Is there anyway to fill swagger documentation fields ?
For example: required, format, min_length, etc.

In structs we can do it via comments:

// Customer customer
// swagger:model customer

type Customer struct {

	// agent associated with this customer
	AgentID int32 `json:"agentId,omitempty"`

	// internal identifier of a customer
	// Required: true
	// Read Only: true
	CustomerID int64 `json:"customerId"`
}

How can I reach this documenting my proto files ?

[achew22]

Good news! With @ivucica's recent PR being submitted we now support adding additional fields in the OpenAPIv2 spec. If there are more fields that you need than are available in the example proto then please reopen this bug and we can discuss.

[maksadbek]

Either I am doing something wrong or it is not generating proper swagger specs.

My proto file:

syntax = "proto3";
  
package protos;

import "protoc-gen-swagger/options/annotations.proto";
import "google/api/annotations.proto";

service Users {
        rpc Create(CreateUserRequest) returns (CreateUserResponse) {
                option (google.api.http) = {
                        post: "/users"
                        body: "*"
                };
        }
}

message CreateUserRequest {
        User user = 1;
}

message CreateUserResponse {

}

message User {
        option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
                json_schema: {
                        title: "simple title";
                        required: [ "name" ];
                };
        };

        string name = 1;
}

My Makefile:

default: 
	protoc -I=. -I=$(GOPATH)/src/github.com/google/protobuf/src/ \
                -I=$(GOPATH)/src/github.com/grpc-ecosystem/grpc-gateway \
		-I=$(GOPATH)/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
                --grpc-gateway_out=logtostderr=true:. \
                --go_out=plugins=grpc:. \
		--swagger_out=logtostderr=true:. \
	     	./*.proto

Generated swagger spec:

{
  "swagger": "2.0",
  "info": {
    "title": "api.proto",
    "version": "version not set"
  },
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/users": {
      "post": {
        "operationId": "Create",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/protosCreateUserResponse"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/protosCreateUserRequest"
            }
          }
        ],
        "tags": [
          "Users"
        ]
      }
    }
  },
  "definitions": {
    "protosCreateUserRequest": {
      "type": "object",
      "properties": {
        "user": {
          "$ref": "#/definitions/protosUser"
        }
      }
    },
    "protosCreateUserResponse": {
      "type": "object"
    },
    "protosUser": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  }
}

Swagger does not have required fields or title.

[ivucica]

I think it does. See: https://github.com/OAI/OpenAPI-Specification/blob/fb059ca461bd17b10a9e3e59879f04485886d356/versions/2.0.md

Search for "required": true, and search for "title": "Swagger Sample App".

Not that protoc-gen-swagger generated OpenAPI v3, but this applies to that version of the spec, too: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

Pasting your generated JSON into https://editor.swagger.io also throws no errors.

Why do you believe "title" and "required" should not be generated?

[ivucica]

Oh, you mean the title and required you specified are omitted from the output?

I've added many fields to the schema without adding support for outputting them. I'm sure PRs will be accepted. You'll want to update template.go: https://github.com/grpc-ecosystem/grpc-gateway/blob/8cc3a55af3bcf171a1c23a90c4df9cf591706104/protoc-gen-swagger/genswagger/template.go

[maksadbek]

@ivucica Okay, got it. Thank you for your quick response :)

[andrii-minchekov]

Can protoc-gen-swagger parse proto3 syntax?

[ivucica]

1. This is not a support channel. :-) 2. gRPC is primarily proto3. 3. protoc-gen-swagger is a plugin for protoc, so it doesn’t parse proto files directly. Therefore, yes. 26.12.2017., u 11:09, korisnik Public Repository of A.Minchekov <[email protected]> je napisao:

…

Can protoc-gen-swagger parse proto3 syntax? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.