diff --git a/Makefile b/Makefile index bbfafe3cfd..0fd89d2e72 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,8 @@ IMPORT := github.com/owncloud/$(NAME) BIN := bin DIST := dist HUGO := hugo +PROTO_VERSION := v0 +PROTO_SRC := pkg/proto/$(PROTO_VERSION)/*.proto ifeq ($(OS), Windows_NT) EXECUTABLE := $(NAME).exe @@ -131,6 +133,11 @@ release-check: .PHONY: release-finish release-finish: release-copy release-check +.PHONY: proto-docs-build +proto-docs-build: + go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc; \ + protoc --doc_out=./docs --doc_opt=./docs/grpc.tmpl,grpc.md $(PROTO_SRC) + .PHONY: docs-copy docs-copy: mkdir -p $(HUGO); \ @@ -141,54 +148,19 @@ docs-copy: git remote add origin https://github.com/owncloud/owncloud.github.io; \ git fetch; \ git checkout origin/source -f; \ - rsync --delete -ax ../docs/ content/extensions/$(NAME) + rsync --delete -ax ../docs/*.md content/extensions/$(NAME) .PHONY: docs-build docs-build: cd $(HUGO); hugo .PHONY: docs -docs: docs-copy docs-build +docs: proto-docs-build docs-copy docs-build .PHONY: watch watch: go run github.com/cespare/reflex -c reflex.conf -# $(GOPATH)/bin/protoc-gen-go: -# GO111MODULE=off go get -v github.com/golang/protobuf/protoc-gen-go - -# $(GOPATH)/bin/protoc-gen-micro: -# GO111MODULE=off go get -v github.com/micro/protoc-gen-micro - -# $(GOPATH)/bin/protoc-gen-microweb: -# GO111MODULE=off go get -v github.com/webhippie/protoc-gen-microweb - -# $(GOPATH)/bin/protoc-gen-swagger: -# GO111MODULE=off go get -v github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger - -# pkg/proto/v0/example.pb.go: pkg/proto/v0/example.proto -# protoc \ -# -I=third_party/ \ -# -I=pkg/proto/v0/ \ -# --go_out=logtostderr=true:pkg/proto/v0 example.proto - -# pkg/proto/v0/example.pb.micro.go: pkg/proto/v0/example.proto -# protoc \ -# -I=third_party/ \ -# -I=pkg/proto/v0/ \ -# --micro_out=logtostderr=true:pkg/proto/v0 example.proto - -# pkg/proto/v0/example.pb.web.go: pkg/proto/v0/example.proto -# protoc \ -# -I=third_party/ \ -# -I=pkg/proto/v0/ \ -# --microweb_out=logtostderr=true:pkg/proto/v0 example.proto - -# pkg/proto/v0/example.swagger.json: pkg/proto/v0/example.proto -# protoc \ -# -I=third_party/ \ -# -I=pkg/proto/v0/ \ -# --swagger_out=logtostderr=true:pkg/proto/v0 example.proto - -# .PHONY: protobuf -# protobuf: $(GOPATH)/bin/protoc-gen-go $(GOPATH)/bin/protoc-gen-micro $(GOPATH)/bin/protoc-gen-microweb $(GOPATH)/bin/protoc-gen-swagger pkg/proto/v0/example.pb.go pkg/proto/v0/example.pb.micro.go pkg/proto/v0/example.pb.web.go pkg/proto/v0/example.swagger.json +.PHONY: pb +pb: + protoc --go_out=. --micro_out=. $(PROTO_SRC) diff --git a/docs/grpc.md b/docs/grpc.md new file mode 100644 index 0000000000..ccb334b791 --- /dev/null +++ b/docs/grpc.md @@ -0,0 +1,119 @@ +--- +title: "GRPC API" +date: 2018-05-02T00:00:00+00:00 +weight: 40 +geekdocRepo: https://github.com/owncloud/ocis-thumbnails +geekdocEditPath: edit/master/docs +geekdocFilePath: grpc.md +--- + + + +## Table of Contents + +- [pkg/proto/v0/thumbnails.proto](#pkg/proto/v0/thumbnails.proto) + - [GetRequest](#com.owncloud.ocis.thumbnails.v0.GetRequest) + - [GetResponse](#com.owncloud.ocis.thumbnails.v0.GetResponse) + + - [GetRequest.FileType](#com.owncloud.ocis.thumbnails.v0.GetRequest.FileType) + + - [ThumbnailService](#com.owncloud.ocis.thumbnails.v0.ThumbnailService) + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## pkg/proto/v0/thumbnails.proto + + + + + +### GetRequest +A request to retrieve a thumbnail + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| filepath | [string](#string) | | The path to the source image | +| filetype | [GetRequest.FileType](#com.owncloud.ocis.thumbnails.v0.GetRequest.FileType) | | The type to which the thumbnail should get encoded to. | +| etag | [string](#string) | | The etag of the source image | +| width | [int32](#int32) | | The width of the thumbnail | +| height | [int32](#int32) | | The height of the thumbnail | +| authorization | [string](#string) | | The authorization token | + + + + + + + + +### GetResponse +The service response + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| thumbnail | [bytes](#bytes) | | The thumbnail as a binary | +| mimetype | [string](#string) | | The mimetype of the thumbnail | + + + + + + + + + + +### GetRequest.FileType +The file types to which the thumbnail cna get encoded to. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| PNG | 0 | Represents PNG type | +| JPG | 1 | Represents JPG type | + + + + + + + + + +### ThumbnailService +A Service for handling thumbnail generation + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| GetThumbnail | [GetRequest](#com.owncloud.ocis.thumbnails.v0.GetRequest) | [GetResponse](#com.owncloud.ocis.thumbnails.v0.GetResponse) | Generates the thumbnail and returns it. | + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | +| double | | double | double | float | float64 | double | float | Float | +| float | | float | float | float | float32 | float | float | Float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | +| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | + diff --git a/docs/grpc.tmpl b/docs/grpc.tmpl new file mode 100644 index 0000000000..814a8713b4 --- /dev/null +++ b/docs/grpc.tmpl @@ -0,0 +1,112 @@ +--- +title: "GRPC API" +date: 2018-05-02T00:00:00+00:00 +weight: 40 +geekdocRepo: https://github.com/owncloud/ocis-thumbnails +geekdocEditPath: edit/master/docs +geekdocFilePath: grpc.md +--- + + + +## Table of Contents +{{range .Files}} +{{$file_name := .Name}}- [{{.Name}}](#{{.Name}}) + {{- if .Messages }} + {{range .Messages}} - [{{.LongName}}](#{{.FullName}}) + {{end}} + {{- end -}} + {{- if .Enums }} + {{range .Enums}} - [{{.LongName}}](#{{.FullName}}) + {{end}} + {{- end -}} + {{- if .Extensions }} + {{range .Extensions}} - [File-level Extensions](#{{$file_name}}-extensions) + {{end}} + {{- end -}} + {{- if .Services }} + {{range .Services}} - [{{.Name}}](#{{.FullName}}) + {{end}} + {{- end -}} +{{end}} +- [Scalar Value Types](#scalar-value-types) + +{{range .Files}} +{{$file_name := .Name}} + +

Top

+ +## {{.Name}} +{{.Description}} + +{{range .Messages}} + + +### {{.LongName}} +{{.Description}} + +{{if .HasFields}} +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +{{range .Fields -}} + | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | +{{end}} +{{end}} + +{{if .HasExtensions}} +| Extension | Type | Base | Number | Description | +| --------- | ---- | ---- | ------ | ----------- | +{{range .Extensions -}} + | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | +{{end}} +{{end}} + +{{end}} + +{{range .Enums}} + + +### {{.LongName}} +{{.Description}} + +| Name | Number | Description | +| ---- | ------ | ----------- | +{{range .Values -}} + | {{.Name}} | {{.Number}} | {{nobr .Description}} | +{{end}} + +{{end}} + +{{if .HasExtensions}} + + +### File-level Extensions +| Extension | Type | Base | Number | Description | +| --------- | ---- | ---- | ------ | ----------- | +{{range .Extensions -}} + | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}} | +{{end}} +{{end}} + +{{range .Services}} + + +### {{.Name}} +{{.Description}} + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +{{range .Methods -}} + | {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType}}){{if .ResponseStreaming}} stream{{end}} | {{nobr .Description}} | +{{end}} +{{end}} + +{{end}} + +## Scalar Value Types + +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | +{{range .Scalars -}} + | {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} | +{{end}} diff --git a/docs/license.md b/docs/license.md index 17bd89d71f..273e92c3b0 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,7 +1,7 @@ --- title: "License" date: 2018-05-02T00:00:00+00:00 -weight: 40 +weight: 50 geekdocRepo: https://github.com/owncloud/ocis-thumbnails geekdocEditPath: edit/master/docs geekdocFilePath: license.md diff --git a/pkg/proto/v0/thumbnails.proto b/pkg/proto/v0/thumbnails.proto index 261a65b134..9b1f6476a3 100644 --- a/pkg/proto/v0/thumbnails.proto +++ b/pkg/proto/v0/thumbnails.proto @@ -3,24 +3,37 @@ syntax = "proto3"; package com.owncloud.ocis.thumbnails.v0; option go_package = "proto"; +// A Service for handling thumbnail generation service ThumbnailService { + // Generates the thumbnail and returns it. rpc GetThumbnail(GetRequest) returns (GetResponse); } +// A request to retrieve a thumbnail message GetRequest { + // The path to the source image string filepath = 1; + // The file types to which the thumbnail cna get encoded to. enum FileType { - PNG = 0; - JPG = 1; + PNG = 0; // Represents PNG type + JPG = 1; // Represents JPG type } + // The type to which the thumbnail should get encoded to. FileType filetype = 2; + // The etag of the source image string etag = 3; + // The width of the thumbnail int32 width = 4; + // The height of the thumbnail int32 height = 5; + // The authorization token string authorization = 6; } +// The service response message GetResponse { + // The thumbnail as a binary bytes thumbnail = 1; + // The mimetype of the thumbnail string mimetype = 2; } \ No newline at end of file