From b256c1f80be5ef3e835c176791356f25df52d073 Mon Sep 17 00:00:00 2001 From: Nex Date: Sat, 5 Dec 2020 11:11:36 +0800 Subject: [PATCH] docs: add OpenAPI docs --- .../bdware/bdledger/api/common.swagger.json | 46 +++ .../bdledger/api/error_details.swagger.json | 46 +++ .../bdware/bdledger/api/ledger.swagger.json | 111 +++++++ .../bdware/bdledger/api/node.swagger.json | 54 +++ .../bdware/bdledger/api/query.swagger.json | 310 ++++++++++++++++++ grpc/scripts/gen.bat | 7 +- grpc/scripts/gen.sh | 7 +- 7 files changed, 579 insertions(+), 2 deletions(-) create mode 100644 docs/openapiv2/bdware/bdledger/api/common.swagger.json create mode 100644 docs/openapiv2/bdware/bdledger/api/error_details.swagger.json create mode 100644 docs/openapiv2/bdware/bdledger/api/ledger.swagger.json create mode 100644 docs/openapiv2/bdware/bdledger/api/node.swagger.json create mode 100644 docs/openapiv2/bdware/bdledger/api/query.swagger.json diff --git a/docs/openapiv2/bdware/bdledger/api/common.swagger.json b/docs/openapiv2/bdware/bdledger/api/common.swagger.json new file mode 100644 index 0000000..3a72efa --- /dev/null +++ b/docs/openapiv2/bdware/bdledger/api/common.swagger.json @@ -0,0 +1,46 @@ +{ + "swagger": "2.0", + "info": { + "title": "bdware/bdledger/api/common.proto", + "version": "version not set" + }, + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": {}, + "definitions": { + "protobufAny": { + "type": "object", + "properties": { + "typeUrl": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +} diff --git a/docs/openapiv2/bdware/bdledger/api/error_details.swagger.json b/docs/openapiv2/bdware/bdledger/api/error_details.swagger.json new file mode 100644 index 0000000..48033c8 --- /dev/null +++ b/docs/openapiv2/bdware/bdledger/api/error_details.swagger.json @@ -0,0 +1,46 @@ +{ + "swagger": "2.0", + "info": { + "title": "bdware/bdledger/api/error_details.proto", + "version": "version not set" + }, + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": {}, + "definitions": { + "protobufAny": { + "type": "object", + "properties": { + "typeUrl": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +} diff --git a/docs/openapiv2/bdware/bdledger/api/ledger.swagger.json b/docs/openapiv2/bdware/bdledger/api/ledger.swagger.json new file mode 100644 index 0000000..1746461 --- /dev/null +++ b/docs/openapiv2/bdware/bdledger/api/ledger.swagger.json @@ -0,0 +1,111 @@ +{ + "swagger": "2.0", + "info": { + "title": "bdware/bdledger/api/ledger.proto", + "version": "version not set" + }, + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": {}, + "definitions": { + "apiCreateLedgerResponse": { + "type": "object", + "properties": { + "ok": { + "type": "boolean", + "format": "boolean" + } + } + }, + "apiGetLedgersResponse": { + "type": "object", + "properties": { + "ledgers": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "apiSendTransactionRequestTransaction": { + "type": "object", + "properties": { + "type": { + "$ref": "#/definitions/apiTransactionType" + }, + "from": { + "type": "string", + "format": "byte" + }, + "nonce": { + "type": "string", + "format": "uint64" + }, + "to": { + "type": "string", + "format": "byte" + }, + "data": { + "type": "string", + "format": "byte" + } + } + }, + "apiSendTransactionResponse": { + "type": "object", + "properties": { + "hash": { + "type": "string", + "format": "byte" + } + } + }, + "apiTransactionType": { + "type": "string", + "enum": [ + "RECORD", + "MESSAGE", + "CONTRACT_CREATION", + "CONTRACT_INVOCATION", + "CONTRACT_STATUS" + ], + "default": "RECORD", + "title": "事务类型" + }, + "protobufAny": { + "type": "object", + "properties": { + "typeUrl": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +} diff --git a/docs/openapiv2/bdware/bdledger/api/node.swagger.json b/docs/openapiv2/bdware/bdledger/api/node.swagger.json new file mode 100644 index 0000000..28ae79c --- /dev/null +++ b/docs/openapiv2/bdware/bdledger/api/node.swagger.json @@ -0,0 +1,54 @@ +{ + "swagger": "2.0", + "info": { + "title": "bdware/bdledger/api/node.proto", + "version": "version not set" + }, + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": {}, + "definitions": { + "apiClientVersionResponse": { + "type": "object", + "properties": { + "version": { + "type": "string" + } + } + }, + "protobufAny": { + "type": "object", + "properties": { + "typeUrl": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +} diff --git a/docs/openapiv2/bdware/bdledger/api/query.swagger.json b/docs/openapiv2/bdware/bdledger/api/query.swagger.json new file mode 100644 index 0000000..d1392f0 --- /dev/null +++ b/docs/openapiv2/bdware/bdledger/api/query.swagger.json @@ -0,0 +1,310 @@ +{ + "swagger": "2.0", + "info": { + "title": "bdware/bdledger/api/query.proto", + "version": "version not set" + }, + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": {}, + "definitions": { + "apiBlock": { + "type": "object", + "properties": { + "hash": { + "type": "string", + "format": "byte" + }, + "creator": { + "type": "string", + "format": "byte" + }, + "nonce": { + "type": "string", + "format": "uint64" + }, + "parentHashes": { + "type": "array", + "items": { + "type": "string", + "format": "byte" + } + }, + "witnesses": { + "type": "array", + "items": { + "type": "string", + "format": "byte" + } + }, + "timestamp": { + "type": "string", + "format": "int64" + }, + "size": { + "type": "string", + "format": "uint64" + }, + "transactionCount": { + "type": "integer", + "format": "int64" + }, + "transactionsRoot": { + "type": "string", + "format": "byte" + }, + "transactions": { + "type": "array", + "items": { + "$ref": "#/definitions/bdledgerapiTransaction" + } + }, + "transactionHashes": { + "type": "array", + "items": { + "type": "string", + "format": "byte" + } + } + } + }, + "apiBlockFilter": { + "type": "object", + "properties": { + "hash": { + "type": "string", + "format": "byte" + }, + "timestamp": { + "type": "string", + "format": "int64" + } + } + }, + "apiCountBlocksResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "uint64" + }, + "startTimestamp": { + "type": "string", + "format": "int64" + }, + "endTimestamp": { + "type": "string", + "format": "int64" + } + } + }, + "apiCountTransactionsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "uint64" + }, + "startTimestamp": { + "type": "string", + "format": "int64" + }, + "endTimestamp": { + "type": "string", + "format": "int64" + } + } + }, + "apiGetBlockByHashResponse": { + "type": "object", + "properties": { + "block": { + "$ref": "#/definitions/apiBlock" + } + } + }, + "apiGetBlocksResponse": { + "type": "object", + "properties": { + "blocks": { + "type": "array", + "items": { + "$ref": "#/definitions/apiBlock" + } + }, + "startTimestamp": { + "type": "string", + "format": "int64" + }, + "endTimestamp": { + "type": "string", + "format": "int64" + } + } + }, + "apiGetTransactionByBlockHashAndIndexResponse": { + "type": "object", + "properties": { + "transaction": { + "$ref": "#/definitions/bdledgerapiTransaction" + } + } + }, + "apiGetTransactionByHashResponse": { + "type": "object", + "properties": { + "transaction": { + "$ref": "#/definitions/bdledgerapiTransaction" + } + } + }, + "apiGetTransactionsResponse": { + "type": "object", + "properties": { + "transactions": { + "type": "array", + "items": { + "$ref": "#/definitions/bdledgerapiTransaction" + } + }, + "startTimestamp": { + "type": "string", + "format": "int64" + }, + "endTimestamp": { + "type": "string", + "format": "int64" + } + } + }, + "apiIncludeTransactions": { + "type": "string", + "enum": [ + "NONE", + "HASH", + "FULL" + ], + "default": "NONE" + }, + "apiTransactionFilter": { + "type": "object", + "properties": { + "hash": { + "type": "string", + "format": "byte" + }, + "from": { + "type": "string", + "format": "byte" + }, + "to": { + "type": "string", + "format": "byte" + }, + "timestamp": { + "type": "string", + "format": "byte" + } + }, + "title": "repeated Transaction/BlockFilters are combined by \"\u0026\u0026\"(and) operator;" + }, + "apiTransactionType": { + "type": "string", + "enum": [ + "RECORD", + "MESSAGE", + "CONTRACT_CREATION", + "CONTRACT_INVOCATION", + "CONTRACT_STATUS" + ], + "default": "RECORD", + "title": "事务类型" + }, + "bdledgerapiTransaction": { + "type": "object", + "properties": { + "blockHash": { + "type": "string", + "format": "byte" + }, + "blockTimestamp": { + "type": "string", + "format": "int64" + }, + "index": { + "type": "integer", + "format": "int64" + }, + "hash": { + "type": "string", + "format": "byte" + }, + "type": { + "$ref": "#/definitions/apiTransactionType" + }, + "from": { + "type": "string", + "format": "byte" + }, + "nonce": { + "type": "string", + "format": "uint64" + }, + "to": { + "type": "string", + "format": "byte" + }, + "data": { + "type": "string", + "format": "byte" + }, + "v": { + "type": "string", + "format": "byte" + }, + "r": { + "type": "string", + "format": "byte" + }, + "s": { + "type": "string", + "format": "byte" + } + } + }, + "protobufAny": { + "type": "object", + "properties": { + "typeUrl": { + "type": "string" + }, + "value": { + "type": "string", + "format": "byte" + } + } + }, + "rpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/protobufAny" + } + } + } + } + } +} diff --git a/grpc/scripts/gen.bat b/grpc/scripts/gen.bat index 8178238..f28d1f2 100644 --- a/grpc/scripts/gen.bat +++ b/grpc/scripts/gen.bat @@ -32,7 +32,12 @@ for %%A in (%*) do ( if not exist !out! mkdir !out! echo Generating Go HTTP code !cmd! ^ - --grpc-gateway_out=grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml,logtostderr=true:!out! ^ + --grpc-gateway_out !out! ^ + --grpc-gateway_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml ^ + --grpc-gateway_opt logtostderr=true ^ + --openapiv2_out ..\..\docs\openapiv2 ^ + --openapiv2_out grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml ^ + --openapiv2_opt logtostderr=true ^ %pb_files% ) if "%%A"=="nodejs" ( diff --git a/grpc/scripts/gen.sh b/grpc/scripts/gen.sh index 10770b1..d785745 100755 --- a/grpc/scripts/gen.sh +++ b/grpc/scripts/gen.sh @@ -64,7 +64,12 @@ do fi echo "Generating Go HTTP code" $cmd \ - --grpc-gateway_out=grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml,logtostderr=true:$out \ + --grpc-gateway_out $out \ + --grpc-gateway_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml \ + --grpc-gateway_opt logtostderr=true \ + --openapiv2_out ../../docs/openapiv2 \ + --openapiv2_out grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml \ + --openapiv2_opt logtostderr=true \ $pb_files \ $async_tag fi