From c32500be0278689dba8b3a79718c9afe2e07aea1 Mon Sep 17 00:00:00 2001 From: Moiseev Ilya Date: Fri, 16 Aug 2024 11:17:39 +0400 Subject: [PATCH] improve: swagger schema structure --- api/openapi.json | 148 ++++++++++++- api/openapi.yml | 342 +++++++++++++++++++------------ pkg/oas/oas_handlers_gen.go | 2 + pkg/oas/oas_server_gen.go | 2 + pkg/oas/oas_unimplemented_gen.go | 2 + 5 files changed, 357 insertions(+), 139 deletions(-) diff --git a/api/openapi.json b/api/openapi.json index 4d43a297..ff8bbce2 100644 --- a/api/openapi.json +++ b/api/openapi.json @@ -6425,7 +6425,8 @@ } }, "tags": [ - "Emulation" + "Emulation", + "Accounts" ] } }, @@ -6846,7 +6847,8 @@ }, "tags": [ "NFT" - ] + ], + "x-question": "duplicate of getNftHistoryByID ?" } }, "/v2/accounts/{account_id}/publickey": { @@ -7065,7 +7067,7 @@ } }, "tags": [ - "Accounts" + "Utilities" ] } }, @@ -7811,7 +7813,8 @@ } }, "tags": [ - "Emulation" + "Emulation", + "Events" ] } }, @@ -8169,7 +8172,7 @@ }, "/v2/gasless/estimate/{master_id}": { "post": { - "description": "Estimates the cost of the given messages and returns a payload to sign.", + "description": "Estimates the cost of the given messages and returns a payload to sign", "operationId": "gaslessEstimate", "parameters": [ { @@ -8209,6 +8212,7 @@ }, "/v2/gasless/send": { "post": { + "description": "Submits the signed gasless transaction message to the network", "operationId": "gaslessSend", "requestBody": { "$ref": "#/components/requestBodies/GaslessSend" @@ -10077,7 +10081,7 @@ } }, "tags": [ - "Blockchain" + "Utilities" ] } }, @@ -10209,7 +10213,8 @@ } }, "tags": [ - "Emulation" + "Emulation", + "Traces" ] } }, @@ -10376,6 +10381,7 @@ } }, "tags": [ + "Wallet", "Emulation" ] } @@ -10420,5 +10426,133 @@ { "url": "http://localhost:8081" } + ], + "tags": [ + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/accounts" + }, + "name": "Accounts" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/nft" + }, + "name": "NFT" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/jettons" + }, + "name": "Jettons" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/dns" + }, + "name": "DNS" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/wallet" + }, + "name": "Wallet" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/rates" + }, + "name": "Rates" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/staking" + }, + "name": "Staking" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/traces" + }, + "name": "Traces" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/events" + }, + "name": "Events" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/storage" + }, + "name": "Storage" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/connect" + }, + "name": "Connect" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/gasless" + }, + "name": "Gasless" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/multisig" + }, + "name": "Multisig" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/blockchain" + }, + "name": "Blockchain" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/liteserver" + }, + "name": "Lite Server" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/emulation" + }, + "name": "Emulation" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/inscriptions" + }, + "name": "Inscriptions" + }, + { + "externalDocs": { + "description": "Additional documentation", + "url": "http://79.137.199.63:3000/tonapi/rest-api/utilities" + }, + "name": "Utilities" + } ] } diff --git a/api/openapi.yml b/api/openapi.yml index e8a8d439..16aea0e9 100644 --- a/api/openapi.yml +++ b/api/openapi.yml @@ -10,13 +10,88 @@ servers: - url: "https://tonapi.io" - url: "https://testnet.tonapi.io" - url: "http://localhost:8081" + +tags: + - name: Accounts + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/accounts + - name: NFT + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/nft + - name: Jettons + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/jettons + - name: DNS + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/dns + - name: Wallet + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/wallet + - name: Rates + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/rates + - name: Staking + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/staking + - name: Traces + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/traces + - name: Events + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/events + - name: Storage + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/storage + - name: Connect + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/connect + - name: Gasless + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/gasless + - name: Multisig + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/multisig + - name: Blockchain + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/blockchain + - name: Lite Server + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/liteserver + - name: Emulation + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/emulation + - name: Inscriptions + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/inscriptions + - name: Utilities + externalDocs: + description: Additional documentation + url: http://79.137.199.63:3000/tonapi/rest-api/utilities + paths: /v2/status: get: description: Status operationId: status tags: - - Blockchain + - Utilities responses: '200': description: status @@ -390,29 +465,12 @@ paths: $ref: '#/components/schemas/BlockchainAccountInspect' 'default': $ref: '#/components/responses/Error' - /v2/message/decode: - post: - description: Decode a given message. Only external incoming messages can be decoded currently. - operationId: decodeMessage - tags: - - Emulation - requestBody: - $ref: "#/components/requestBodies/Boc" - responses: - '200': - description: decoded message - content: - application/json: - schema: - $ref: '#/components/schemas/DecodedMessage' - 'default': - $ref: '#/components/responses/Error' /v2/address/{account_id}/parse: get: description: parse address and display in all formats operationId: addressParse tags: - - Accounts + - Utilities parameters: - $ref: '#/components/parameters/accountIDParameter' responses: @@ -459,99 +517,6 @@ paths: type: boolean default: $ref: '#/components/responses/Error' - - /v2/events/emulate: - post: - description: Emulate sending message to blockchain - operationId: emulateMessageToEvent - tags: - - Emulation - parameters: - - $ref: '#/components/parameters/i18n' - - name: ignore_signature_check - in: query - required: false - schema: - type: boolean - requestBody: - $ref: "#/components/requestBodies/Boc" - responses: - '200': - description: emulated event - content: - application/json: - schema: - $ref: '#/components/schemas/Event' - 'default': - $ref: '#/components/responses/Error' - /v2/traces/emulate: - post: - description: Emulate sending message to blockchain - operationId: emulateMessageToTrace - tags: - - Emulation - parameters: - - name: ignore_signature_check - in: query - required: false - schema: - type: boolean - requestBody: - $ref: "#/components/requestBodies/Boc" - responses: - '200': - description: emulated trace - content: - application/json: - schema: - $ref: '#/components/schemas/Trace' - 'default': - $ref: '#/components/responses/Error' - /v2/wallet/emulate: - post: - description: Emulate sending message to blockchain - operationId: emulateMessageToWallet - tags: - - Emulation - parameters: - - $ref: '#/components/parameters/i18n' - requestBody: - $ref: "#/components/requestBodies/EmulationBoc" - responses: - '200': - description: emulated message - content: - application/json: - schema: - $ref: '#/components/schemas/MessageConsequences' - 'default': - $ref: '#/components/responses/Error' - /v2/accounts/{account_id}/events/emulate: - post: - description: Emulate sending message to blockchain - operationId: emulateMessageToAccountEvent - tags: - - Emulation - parameters: - - $ref: '#/components/parameters/i18n' - - $ref: '#/components/parameters/accountIDParameter' - - name: ignore_signature_check - in: query - required: false - schema: - type: boolean - requestBody: - $ref: "#/components/requestBodies/Boc" - responses: - '200': - description: emulated message to account - content: - application/json: - schema: - $ref: '#/components/schemas/AccountEvent' - 'default': - $ref: '#/components/responses/Error' - /v2/accounts/_bulk: post: description: Get human-friendly information about several accounts without low-level details. @@ -771,6 +736,7 @@ paths: $ref: '#/components/responses/Error' /v2/accounts/{account_id}/nfts/history: get: + x-question: duplicate of getNftHistoryByID ? description: Get the transfer nft history operationId: getAccountNftHistory tags: @@ -1981,9 +1947,26 @@ paths: example: "NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2ODQ3..." 'default': $ref: '#/components/responses/Error' + /v2/wallet/{account_id}/seqno: + get: + description: Get account seqno + operationId: getAccountSeqno + tags: + - Wallet + parameters: + - $ref: '#/components/parameters/accountIDParameter' + responses: + '200': + description: account seqno + content: + application/json: + schema: + $ref: '#/components/schemas/Seqno' + 'default': + $ref: '#/components/responses/Error' /v2/gasless/config: get: - description: "Returns configuration of gasless transfers" + description: Returns configuration of gasless transfers operationId: gaslessConfig tags: - Gasless @@ -1998,7 +1981,7 @@ paths: $ref: '#/components/responses/Error' /v2/gasless/estimate/{master_id}: post: - description: "Estimates the cost of the given messages and returns a payload to sign." + description: Estimates the cost of the given messages and returns a payload to sign operationId: gaslessEstimate parameters: - name: master_id @@ -2024,6 +2007,7 @@ paths: $ref: '#/components/responses/Error' /v2/gasless/send: post: + description: Submits the signed gasless transaction message to the network operationId: gaslessSend tags: - Gasless @@ -2051,23 +2035,6 @@ paths: $ref: '#/components/schemas/Accounts' 'default': $ref: '#/components/responses/Error' - /v2/wallet/{account_id}/seqno: - get: - description: Get account seqno - operationId: getAccountSeqno - tags: - - Wallet - parameters: - - $ref: '#/components/parameters/accountIDParameter' - responses: - '200': - description: account seqno - content: - application/json: - schema: - $ref: '#/components/schemas/Seqno' - 'default': - $ref: '#/components/responses/Error' /v2/liteserver/get_masterchain_info: get: @@ -2725,7 +2692,118 @@ paths: $ref: '#/components/schemas/Multisig' 'default': $ref: '#/components/responses/Error' - + /v2/message/decode: + post: + description: Decode a given message. Only external incoming messages can be decoded currently. + operationId: decodeMessage + tags: + - Emulation + requestBody: + $ref: "#/components/requestBodies/Boc" + responses: + '200': + description: decoded message + content: + application/json: + schema: + $ref: '#/components/schemas/DecodedMessage' + 'default': + $ref: '#/components/responses/Error' + /v2/events/emulate: + post: + description: Emulate sending message to blockchain + operationId: emulateMessageToEvent + tags: + - Emulation + - Events + parameters: + - $ref: '#/components/parameters/i18n' + - name: ignore_signature_check + in: query + required: false + schema: + type: boolean + requestBody: + $ref: "#/components/requestBodies/Boc" + responses: + '200': + description: emulated event + content: + application/json: + schema: + $ref: '#/components/schemas/Event' + 'default': + $ref: '#/components/responses/Error' + /v2/traces/emulate: + post: + description: Emulate sending message to blockchain + operationId: emulateMessageToTrace + tags: + - Emulation + - Traces + parameters: + - name: ignore_signature_check + in: query + required: false + schema: + type: boolean + requestBody: + $ref: "#/components/requestBodies/Boc" + responses: + '200': + description: emulated trace + content: + application/json: + schema: + $ref: '#/components/schemas/Trace' + 'default': + $ref: '#/components/responses/Error' + /v2/wallet/emulate: + post: + description: Emulate sending message to blockchain + operationId: emulateMessageToWallet + tags: + - Wallet + - Emulation + parameters: + - $ref: '#/components/parameters/i18n' + requestBody: + $ref: "#/components/requestBodies/EmulationBoc" + responses: + '200': + description: emulated message + content: + application/json: + schema: + $ref: '#/components/schemas/MessageConsequences' + 'default': + $ref: '#/components/responses/Error' + /v2/accounts/{account_id}/events/emulate: + post: + description: Emulate sending message to blockchain + operationId: emulateMessageToAccountEvent + tags: + - Emulation + - Accounts + parameters: + - $ref: '#/components/parameters/i18n' + - $ref: '#/components/parameters/accountIDParameter' + - name: ignore_signature_check + in: query + required: false + schema: + type: boolean + requestBody: + $ref: "#/components/requestBodies/Boc" + responses: + '200': + description: emulated message to account + content: + application/json: + schema: + $ref: '#/components/schemas/AccountEvent' + 'default': + $ref: '#/components/responses/Error' components: parameters: masterchainSeqno: diff --git a/pkg/oas/oas_handlers_gen.go b/pkg/oas/oas_handlers_gen.go index 6d82709e..6bbc6fd0 100644 --- a/pkg/oas/oas_handlers_gen.go +++ b/pkg/oas/oas_handlers_gen.go @@ -1502,6 +1502,8 @@ func (s *Server) handleGaslessEstimateRequest(args [1]string, argsEscaped bool, // handleGaslessSendRequest handles gaslessSend operation. // +// Submits the signed gasless transaction message to the network. +// // POST /v2/gasless/send func (s *Server) handleGaslessSendRequest(args [0]string, argsEscaped bool, w http.ResponseWriter, r *http.Request) { otelAttrs := []attribute.KeyValue{ diff --git a/pkg/oas/oas_server_gen.go b/pkg/oas/oas_server_gen.go index 11b261ec..898be9d1 100644 --- a/pkg/oas/oas_server_gen.go +++ b/pkg/oas/oas_server_gen.go @@ -82,6 +82,8 @@ type Handler interface { GaslessEstimate(ctx context.Context, req *GaslessEstimateReq, params GaslessEstimateParams) (*SignRawParams, error) // GaslessSend implements gaslessSend operation. // + // Submits the signed gasless transaction message to the network. + // // POST /v2/gasless/send GaslessSend(ctx context.Context, req *GaslessSendReq) error // GetAccount implements getAccount operation. diff --git a/pkg/oas/oas_unimplemented_gen.go b/pkg/oas/oas_unimplemented_gen.go index c0be486a..ff9e7558 100644 --- a/pkg/oas/oas_unimplemented_gen.go +++ b/pkg/oas/oas_unimplemented_gen.go @@ -123,6 +123,8 @@ func (UnimplementedHandler) GaslessEstimate(ctx context.Context, req *GaslessEst // GaslessSend implements gaslessSend operation. // +// Submits the signed gasless transaction message to the network. +// // POST /v2/gasless/send func (UnimplementedHandler) GaslessSend(ctx context.Context, req *GaslessSendReq) error { return ht.ErrNotImplemented