From b412af2e22c2e4a2694ba171458ee42f598f7fa9 Mon Sep 17 00:00:00 2001 From: Denis Kirillov Date: Wed, 20 Jul 2022 18:16:30 +0300 Subject: [PATCH] [#24] Update examples and description in spec Signed-off-by: Denis Kirillov --- gen/models/action.go | 2 +- gen/models/address.go | 2 +- gen/models/attribute.go | 3 +- gen/models/bearer.go | 3 +- gen/models/container_info.go | 4 +- gen/models/container_list.go | 3 +- gen/models/container_put_info.go | 2 +- gen/models/eacl.go | 3 +- gen/models/error_response.go | 3 +- gen/models/error_type.go | 2 +- gen/models/filter.go | 2 +- gen/models/header_type.go | 2 +- gen/models/match_type.go | 2 +- gen/models/object_base_info.go | 3 +- gen/models/object_info.go | 2 +- gen/models/object_list.go | 3 +- gen/models/object_upload.go | 2 +- gen/models/operation.go | 2 +- gen/models/record.go | 2 +- gen/models/role.go | 2 +- gen/models/rule.go | 3 +- gen/models/search_filter.go | 3 +- gen/models/search_filters.go | 3 +- gen/models/search_match.go | 2 +- gen/models/success_response.go | 3 +- gen/models/target.go | 2 +- gen/models/token_response.go | 4 +- gen/models/token_type.go | 2 +- gen/models/verb.go | 2 +- gen/restapi/doc.go | 2 +- gen/restapi/embedded_spec.go | 524 +++++++++++++++--- gen/restapi/operations/auth.go | 2 +- gen/restapi/operations/auth_parameters.go | 6 +- gen/restapi/operations/auth_responses.go | 2 +- .../operations/delete_container_parameters.go | 8 +- .../operations/delete_container_responses.go | 4 +- .../operations/delete_object_parameters.go | 10 +- .../operations/delete_object_responses.go | 4 +- .../get_container_e_acl_parameters.go | 2 +- .../get_container_e_acl_responses.go | 4 +- .../operations/get_container_parameters.go | 2 +- .../operations/get_container_responses.go | 4 +- .../operations/get_object_info_parameters.go | 14 +- .../operations/list_containers_parameters.go | 2 +- .../operations/list_containers_responses.go | 4 +- gen/restapi/operations/neofs_rest_gw_api.go | 2 +- .../put_container_e_acl_parameters.go | 10 +- .../put_container_e_acl_responses.go | 4 +- .../operations/put_container_parameters.go | 8 +- .../operations/put_container_responses.go | 4 +- .../operations/put_object_parameters.go | 6 +- .../operations/search_objects_parameters.go | 10 +- spec/rest.yaml | 181 ++++-- 53 files changed, 685 insertions(+), 207 deletions(-) diff --git a/gen/models/action.go b/gen/models/action.go index ffa9062..4824fdf 100644 --- a/gen/models/action.go +++ b/gen/models/action.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Action action +// Action Rule execution result action in NeoFS EACL. Either allows or denies access if the rule's filters match. // // swagger:model Action type Action string diff --git a/gen/models/address.go b/gen/models/address.go index d20c544..1fd4b83 100644 --- a/gen/models/address.go +++ b/gen/models/address.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Address address +// Address Address of the object in NeoFS. // Example: {"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","objectId":"8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd"} // // swagger:model Address diff --git a/gen/models/attribute.go b/gen/models/attribute.go index bfec64d..1765839 100644 --- a/gen/models/attribute.go +++ b/gen/models/attribute.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// Attribute attribute +// Attribute Attribute is a pair of strings that can be attached to a container or an object. +// Example: {"key":"User-Defined-Tag","value":"tag value"} // // swagger:model Attribute type Attribute struct { diff --git a/gen/models/bearer.go b/gen/models/bearer.go index 23e4e60..aac230c 100644 --- a/gen/models/bearer.go +++ b/gen/models/bearer.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/swag" ) -// Bearer bearer +// Bearer Bearer token that is expected to be formed. +// Example: [{"name":"my-bearer-token","object":[{"action":"ALLOW","filters":[],"operation":"GET","targets":[{"keys":[],"role":"OTHERS"}]}]},{"container":{"verb":"PUT"},"name":"my token to create container"}] // // swagger:model Bearer type Bearer struct { diff --git a/gen/models/container_info.go b/gen/models/container_info.go index 31e9823..3eac1fa 100644 --- a/gen/models/container_info.go +++ b/gen/models/container_info.go @@ -15,8 +15,8 @@ import ( "github.com/go-openapi/validate" ) -// ContainerInfo container info -// Example: {"attribute":[{"key":"Timestamp","value":"1648810072"},{"key":"Name","value":"container"}],"basicAcl":"0x1fbf9fff","containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","ownerId":"NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM","placementPolicy":"REP 2","version":"2.11"} +// ContainerInfo Information about container. +// Example: {"attribute":[{"key":"Timestamp","value":"1648810072"},{"key":"Name","value":"container"}],"basicAcl":"0x1fbf9fff","containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","containerName":"container","ownerId":"NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM","placementPolicy":"REP 2","version":"2.11"} // // swagger:model ContainerInfo type ContainerInfo struct { diff --git a/gen/models/container_list.go b/gen/models/container_list.go index 759ae94..97cd561 100644 --- a/gen/models/container_list.go +++ b/gen/models/container_list.go @@ -15,7 +15,8 @@ import ( "github.com/go-openapi/validate" ) -// ContainerList container list +// ContainerList List of containers info +// Example: {"containers":[{"attribute":[{"key":"Timestamp","value":"1648810072"},{"key":"Name","value":"container"}],"basicAcl":"0x1fbf9fff","containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","containerName":"container","ownerId":"NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM","placementPolicy":"REP 2","version":"2.11"},{"attribute":[{"key":"Name","value":"container2"}],"basicAcl":"0x1fbf9fff","containerId":"FsE7HLQBBYc2WFJzuTXMcpspDEmwUxsD5YmNb2r25uUu","containerName":"container2","ownerId":"NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM","placementPolicy":"REP 1","version":"2.11"}],"size":2} // // swagger:model ContainerList type ContainerList struct { diff --git a/gen/models/container_put_info.go b/gen/models/container_put_info.go index 8e0b349..32912db 100644 --- a/gen/models/container_put_info.go +++ b/gen/models/container_put_info.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/swag" ) -// ContainerPutInfo Represent request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored). +// ContainerPutInfo Request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored). // Example: {"attributes":[{"key":"Custom-Attribute","value":"value"}],"basicAcl":"public-read-write","containerName":"container","placementPolicy":"REP 3"} // // swagger:model ContainerPutInfo diff --git a/gen/models/eacl.go b/gen/models/eacl.go index c81d34b..6e9d230 100644 --- a/gen/models/eacl.go +++ b/gen/models/eacl.go @@ -15,7 +15,8 @@ import ( "github.com/go-openapi/validate" ) -// Eacl eacl +// Eacl EACL NeoFS table. +// Example: {"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","records":[{"action":"GET","filters":[{"headerType":"OBJECT","key":"FileName","matchType":"STRING_EQUAL","value":"myfile"}],"operation":"ALLOW","targets":[{"role":"OTHERS"}]}]} // // swagger:model Eacl type Eacl struct { diff --git a/gen/models/error_response.go b/gen/models/error_response.go index 981f129..8ec866b 100644 --- a/gen/models/error_response.go +++ b/gen/models/error_response.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// ErrorResponse error response +// ErrorResponse Error response. +// Example: {"code":1024,"message":"incomplete object PUT by placement","type":"API"} // // swagger:model ErrorResponse type ErrorResponse struct { diff --git a/gen/models/error_type.go b/gen/models/error_type.go index b2ac34c..6e05f8e 100644 --- a/gen/models/error_type.go +++ b/gen/models/error_type.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// ErrorType error type +// ErrorType Error type. Allow determine source of the error. // // swagger:model ErrorType type ErrorType string diff --git a/gen/models/filter.go b/gen/models/filter.go index 2b16f88..b7cdc39 100644 --- a/gen/models/filter.go +++ b/gen/models/filter.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Filter filter +// Filter Filter in NeoFS EACL to check particular properties of the request or the object. // Example: {"headerType":"OBJECT","key":"FileName","matchType":"STRING_NOT_EQUAL","value":"myfile"} // // swagger:model Filter diff --git a/gen/models/header_type.go b/gen/models/header_type.go index a40bf0a..95dad47 100644 --- a/gen/models/header_type.go +++ b/gen/models/header_type.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// HeaderType header type +// HeaderType Enumeration of possible sources of Headers to apply filters in NeoFS EACL. // // swagger:model HeaderType type HeaderType string diff --git a/gen/models/match_type.go b/gen/models/match_type.go index 03dfa7f..3982959 100644 --- a/gen/models/match_type.go +++ b/gen/models/match_type.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// MatchType match type +// MatchType Match type in NeoFS EACL filter. // // swagger:model MatchType type MatchType string diff --git a/gen/models/object_base_info.go b/gen/models/object_base_info.go index d0873e7..84ec32a 100644 --- a/gen/models/object_base_info.go +++ b/gen/models/object_base_info.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// ObjectBaseInfo object base info +// ObjectBaseInfo Basic object information. +// Example: {"address":{"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","objectId":"8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd"},"name":"/my/object/name"} // // swagger:model ObjectBaseInfo type ObjectBaseInfo struct { diff --git a/gen/models/object_info.go b/gen/models/object_info.go index 090c062..6018c55 100644 --- a/gen/models/object_info.go +++ b/gen/models/object_info.go @@ -15,7 +15,7 @@ import ( "github.com/go-openapi/validate" ) -// ObjectInfo object info +// ObjectInfo Object information. // Example: {"attribute":[{"key":"Timestamp","value":"1648810072"},{"key":"Name","value":"object"}],"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","objectId":"8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd","ownerId":"NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM"} // // swagger:model ObjectInfo diff --git a/gen/models/object_list.go b/gen/models/object_list.go index fbfc3df..32f2ed4 100644 --- a/gen/models/object_list.go +++ b/gen/models/object_list.go @@ -15,7 +15,8 @@ import ( "github.com/go-openapi/validate" ) -// ObjectList object list +// ObjectList List of objects. +// Example: {"objects":[{"address":{"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","objectId":"8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd"},"name":"/my/object/name"},{"address":{"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","objectId":"3GbmMWusaWgMHokWui2zDunxMTzButuQMVLbtL3cDn8s"},"name":"/my/object/some/other/name"}],"size":2} // // swagger:model ObjectList type ObjectList struct { diff --git a/gen/models/object_upload.go b/gen/models/object_upload.go index dbd67c4..fe91e1b 100644 --- a/gen/models/object_upload.go +++ b/gen/models/object_upload.go @@ -15,7 +15,7 @@ import ( "github.com/go-openapi/validate" ) -// ObjectUpload object upload +// ObjectUpload Request body to create object. // Example: {"attributes":[{"key":"User-Attribute","value":"some-value"}],"containerId":"5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv","fileName":"myFile.txt","payload":"Y29udGVudCBvZiBmaWxl"} // // swagger:model ObjectUpload diff --git a/gen/models/operation.go b/gen/models/operation.go index 4e08e01..0db2e0f 100644 --- a/gen/models/operation.go +++ b/gen/models/operation.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Operation operation +// Operation Request's operation type to match in NeoFS EACL if the rule is applicable to a particular request. // // swagger:model Operation type Operation string diff --git a/gen/models/record.go b/gen/models/record.go index e587b53..d4cbfbb 100644 --- a/gen/models/record.go +++ b/gen/models/record.go @@ -15,7 +15,7 @@ import ( "github.com/go-openapi/validate" ) -// Record record +// Record A single NeoFS EACL rule. // Example: {"action":"ALLOW","filters":[],"operation":"GET","targets":[{"keys":[],"role":"OTHERS"}]} // // swagger:model Record diff --git a/gen/models/role.go b/gen/models/role.go index 8d79005..c39ff79 100644 --- a/gen/models/role.go +++ b/gen/models/role.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Role role +// Role Role for target in EACL. // // swagger:model Role type Role string diff --git a/gen/models/rule.go b/gen/models/rule.go index 1cee028..df44769 100644 --- a/gen/models/rule.go +++ b/gen/models/rule.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// Rule rule +// Rule Container session token rule. +// Example: {"containerId":"6jvKJCQr6e47Yx8SsbSN3fNgzroUJVkY66Q9wqxYcAjc","verb":"DELETE"} // // swagger:model Rule type Rule struct { diff --git a/gen/models/search_filter.go b/gen/models/search_filter.go index 3230bf5..09aa8cc 100644 --- a/gen/models/search_filter.go +++ b/gen/models/search_filter.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// SearchFilter search filter +// SearchFilter Search filter to find objects. +// Example: {"key":"FileName","match":"MatchStringEqual","value":"object-name"} // // swagger:model SearchFilter type SearchFilter struct { diff --git a/gen/models/search_filters.go b/gen/models/search_filters.go index 2d71fcd..4e67744 100644 --- a/gen/models/search_filters.go +++ b/gen/models/search_filters.go @@ -15,7 +15,8 @@ import ( "github.com/go-openapi/validate" ) -// SearchFilters search filters +// SearchFilters List of SearchFilter elements. +// Example: {"filters":[{"key":"FileName","match":"MatchCommonPrefix","value":"some/prefix"},{"key":"CustomAttribute","match":"MatchStringEqual","value":"tag-value"}]} // // swagger:model SearchFilters type SearchFilters struct { diff --git a/gen/models/search_match.go b/gen/models/search_match.go index df81716..5999c1f 100644 --- a/gen/models/search_match.go +++ b/gen/models/search_match.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// SearchMatch search match +// SearchMatch Search match type. // // swagger:model SearchMatch type SearchMatch string diff --git a/gen/models/success_response.go b/gen/models/success_response.go index de2d1f9..083be45 100644 --- a/gen/models/success_response.go +++ b/gen/models/success_response.go @@ -14,7 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// SuccessResponse success response +// SuccessResponse Success response. +// Example: {"success":true} // // swagger:model SuccessResponse type SuccessResponse struct { diff --git a/gen/models/target.go b/gen/models/target.go index ba7389a..f926cc7 100644 --- a/gen/models/target.go +++ b/gen/models/target.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Target target +// Target Target to apply the ACL rule. Can be a subject's role class or a list of public keys to match. // Example: {"keys":["021dc56fc6d81d581ae7605a8e00e0e0bab6cbad566a924a527339475a97a8e38e"],"role":"USER"} // // swagger:model Target diff --git a/gen/models/token_response.go b/gen/models/token_response.go index 6982f3c..fdf85ba 100644 --- a/gen/models/token_response.go +++ b/gen/models/token_response.go @@ -14,8 +14,8 @@ import ( "github.com/go-openapi/validate" ) -// TokenResponse token response -// Example: [{"token":"sometoken-todo-add","type":"object"},{"token":"ChCpanIBJCpJuJz42KOmGMSnEhsKGTWquaX2Lq6GhhO4faOYkLD0f9WkXuYJlq4aBAhnGAMiIQJgFcIEghQB5lq3AJZOVswInwc1IGhlQ7NCUh4DFO3UATIECAEQAQ==","type":"container"}] +// TokenResponse Base64 encoded marshaled token (for container or for object operations). +// Example: [{"token":"ClYKBAgCEA0aCAgDEAEiAggDGggIARACIgIIAxoICAIQAiICCAMaCAgDEAIiAggDGggIBBACIgIIAxoICAUQAiICCAMaCAgGEAIiAggDGggIBxACIgIIAxIbChk182WEDFuAqq3nssrGOaH0NK0ZhzF8bu+YGgQIaBgE","type":"object"},{"token":"ChCpanIBJCpJuJz42KOmGMSnEhsKGTWquaX2Lq6GhhO4faOYkLD0f9WkXuYJlq4aBAhnGAMiIQJgFcIEghQB5lq3AJZOVswInwc1IGhlQ7NCUh4DFO3UATIECAEQAQ==","type":"container"}] // // swagger:model TokenResponse type TokenResponse struct { diff --git a/gen/models/token_type.go b/gen/models/token_type.go index 8fca4e0..40a612b 100644 --- a/gen/models/token_type.go +++ b/gen/models/token_type.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// TokenType token type +// TokenType Type of token. // // swagger:model TokenType type TokenType string diff --git a/gen/models/verb.go b/gen/models/verb.go index 83e3770..0312141 100644 --- a/gen/models/verb.go +++ b/gen/models/verb.go @@ -14,7 +14,7 @@ import ( "github.com/go-openapi/validate" ) -// Verb verb +// Verb Verb that describes the allowed container operation for token. // // swagger:model Verb type Verb string diff --git a/gen/restapi/doc.go b/gen/restapi/doc.go index 433b039..bc68476 100644 --- a/gen/restapi/doc.go +++ b/gen/restapi/doc.go @@ -2,7 +2,7 @@ // Package restapi REST API NeoFS // -// REST API NeoFS +// REST API for native integration with NeoFS. // Schemes: // http // Host: localhost:8090 diff --git a/gen/restapi/embedded_spec.go b/gen/restapi/embedded_spec.go index e8435fa..4cfe306 100644 --- a/gen/restapi/embedded_spec.go +++ b/gen/restapi/embedded_spec.go @@ -23,7 +23,7 @@ func init() { ], "swagger": "2.0", "info": { - "description": "REST API NeoFS", + "description": "REST API for native integration with NeoFS.", "title": "REST API NeoFS", "version": "v1" }, @@ -39,12 +39,12 @@ func init() { "produces": [ "application/json" ], - "summary": "Form bearer token to futher requests", + "summary": "Form bearer token to further requests", "operationId": "auth", "parameters": [ { "type": "string", - "description": "Owner Id (wallet address) that will sign the token", + "description": "Owner Id (wallet address) that will sign the token.", "name": "X-Bearer-Owner-Id", "in": "header", "required": true @@ -52,12 +52,12 @@ func init() { { "type": "integer", "default": 100, - "description": "Token lifetime in epoch", + "description": "Token lifetime in epoch.", "name": "X-Bearer-Lifetime", "in": "header" }, { - "description": "Bearer token", + "description": "Bearer tokens to form.", "name": "tokens", "in": "body", "required": true, @@ -71,7 +71,7 @@ func init() { ], "responses": { "200": { - "description": "Base64 encoded stable binary marshaled bearer token", + "description": "Base64 encoded stable binary marshaled bearer token.", "schema": { "type": "array", "items": { @@ -96,7 +96,7 @@ func init() { "parameters": [ { "type": "string", - "description": "Base58 encoded owner id", + "description": "Base58 encoded owner id.", "name": "ownerId", "in": "query", "required": true @@ -120,13 +120,13 @@ func init() { ], "responses": { "200": { - "description": "Containers info", + "description": "Containers info.", "schema": { "$ref": "#/definitions/ContainerList" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -149,7 +149,7 @@ func init() { { "type": "boolean", "default": false, - "description": "Provide this parameter to register container name in NNS service", + "description": "Provide this parameter to register container name in NNS service.", "name": "name-scope-global", "in": "query" }, @@ -165,7 +165,7 @@ func init() { ], "responses": { "200": { - "description": "Address of uploaded objects", + "description": "Identifier of the created container.", "schema": { "type": "object", "required": [ @@ -182,7 +182,7 @@ func init() { } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -197,13 +197,13 @@ func init() { "operationId": "getContainer", "responses": { "200": { - "description": "Container info", + "description": "Container info.", "schema": { "$ref": "#/definitions/ContainerInfo" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -226,13 +226,13 @@ func init() { ], "responses": { "200": { - "description": "Successful deletion", + "description": "Successful deletion.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -252,13 +252,13 @@ func init() { "operationId": "getContainerEACL", "responses": { "200": { - "description": "Container EACL information", + "description": "Container EACL information.", "schema": { "$ref": "#/definitions/Eacl" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -279,7 +279,7 @@ func init() { "$ref": "#/parameters/signatureScheme" }, { - "description": "EACL for container", + "description": "EACL for container.", "name": "eacl", "in": "body", "required": true, @@ -290,13 +290,13 @@ func init() { ], "responses": { "200": { - "description": "Successful EACL updating", + "description": "Successful EACL updating.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -379,7 +379,7 @@ func init() { "in": "query" }, { - "description": "Filters to search objects", + "description": "Filters to search objects.", "name": "searchFilters", "in": "body", "required": true, @@ -425,12 +425,14 @@ func init() { "parameters": [ { "type": "integer", + "description": "Range offset to start reading data.", "name": "range-offset", "in": "query" }, { "minimum": 1, "type": "integer", + "description": "Length of data range.", "name": "range-length", "in": "query" }, @@ -463,13 +465,13 @@ func init() { "operationId": "deleteObject", "responses": { "200": { - "description": "Successful deletion", + "description": "Successful deletion.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -497,6 +499,7 @@ func init() { }, "definitions": { "Action": { + "description": "Rule execution result action in NeoFS EACL. Either allows or denies access if the rule's filters match.", "type": "string", "enum": [ "ALLOW", @@ -504,6 +507,7 @@ func init() { ] }, "Address": { + "description": "Address of the object in NeoFS.", "type": "object", "required": [ "containerId", @@ -523,6 +527,7 @@ func init() { } }, "Attribute": { + "description": "Attribute is a pair of strings that can be attached to a container or an object.", "type": "object", "required": [ "key", @@ -535,9 +540,14 @@ func init() { "value": { "type": "string" } + }, + "example": { + "key": "User-Defined-Tag", + "value": "tag value" } }, "Bearer": { + "description": "Bearer token that is expected to be formed.", "type": "object", "properties": { "container": { @@ -552,9 +562,34 @@ func init() { "$ref": "#/definitions/Record" } } - } + }, + "example": [ + { + "name": "my-bearer-token", + "object": [ + { + "action": "ALLOW", + "filters": null, + "operation": "GET", + "targets": [ + { + "keys": null, + "role": "OTHERS" + } + ] + } + ] + }, + { + "container": { + "verb": "PUT" + }, + "name": "my token to create container" + } + ] }, "ContainerInfo": { + "description": "Information about container.", "type": "object", "required": [ "containerId", @@ -604,12 +639,14 @@ func init() { ], "basicAcl": "0x1fbf9fff", "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "containerName": "container", "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", "placementPolicy": "REP 2", "version": "2.11" } }, "ContainerList": { + "description": "List of containers info", "type": "object", "required": [ "size", @@ -625,10 +662,47 @@ func init() { "size": { "type": "integer" } + }, + "example": { + "containers": [ + { + "attribute": [ + { + "key": "Timestamp", + "value": "1648810072" + }, + { + "key": "Name", + "value": "container" + } + ], + "basicAcl": "0x1fbf9fff", + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "containerName": "container", + "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", + "placementPolicy": "REP 2", + "version": "2.11" + }, + { + "attribute": [ + { + "key": "Name", + "value": "container2" + } + ], + "basicAcl": "0x1fbf9fff", + "containerId": "FsE7HLQBBYc2WFJzuTXMcpspDEmwUxsD5YmNb2r25uUu", + "containerName": "container2", + "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", + "placementPolicy": "REP 1", + "version": "2.11" + } + ], + "size": 2 } }, "ContainerPutInfo": { - "description": "Represent request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored).", + "description": "Request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored).", "type": "object", "properties": { "attributes": { @@ -660,6 +734,7 @@ func init() { } }, "Eacl": { + "description": "EACL NeoFS table.", "type": "object", "required": [ "records" @@ -675,9 +750,32 @@ func init() { "$ref": "#/definitions/Record" } } + }, + "example": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "records": [ + { + "action": "GET", + "filters": [ + { + "headerType": "OBJECT", + "key": "FileName", + "matchType": "STRING_EQUAL", + "value": "myfile" + } + ], + "operation": "ALLOW", + "targets": [ + { + "role": "OTHERS" + } + ] + } + ] } }, "ErrorResponse": { + "description": "Error response.", "type": "object", "required": [ "type", @@ -693,9 +791,15 @@ func init() { "type": { "$ref": "#/definitions/ErrorType" } + }, + "example": { + "code": 1024, + "message": "incomplete object PUT by placement", + "type": "API" } }, "ErrorType": { + "description": "Error type. Allow determine source of the error.", "type": "string", "enum": [ "GW", @@ -703,6 +807,7 @@ func init() { ] }, "Filter": { + "description": "Filter in NeoFS EACL to check particular properties of the request or the object.", "type": "object", "required": [ "headerType", @@ -732,6 +837,7 @@ func init() { } }, "HeaderType": { + "description": "Enumeration of possible sources of Headers to apply filters in NeoFS EACL.", "type": "string", "enum": [ "REQUEST", @@ -740,6 +846,7 @@ func init() { ] }, "MatchType": { + "description": "Match type in NeoFS EACL filter.", "type": "string", "enum": [ "STRING_EQUAL", @@ -747,6 +854,7 @@ func init() { ] }, "ObjectBaseInfo": { + "description": "Basic object information.", "type": "object", "required": [ "address" @@ -758,9 +866,17 @@ func init() { "name": { "type": "string" } + }, + "example": { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd" + }, + "name": "/my/object/name" } }, "ObjectInfo": { + "description": "Object information.", "type": "object", "required": [ "containerId", @@ -816,6 +932,7 @@ func init() { } }, "ObjectList": { + "description": "List of objects.", "type": "object", "required": [ "size", @@ -831,9 +948,29 @@ func init() { "size": { "type": "integer" } + }, + "example": { + "objects": [ + { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd" + }, + "name": "/my/object/name" + }, + { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "3GbmMWusaWgMHokWui2zDunxMTzButuQMVLbtL3cDn8s" + }, + "name": "/my/object/some/other/name" + } + ], + "size": 2 } }, "ObjectUpload": { + "description": "Request body to create object.", "type": "object", "required": [ "containerId", @@ -869,6 +1006,7 @@ func init() { } }, "Operation": { + "description": "Request's operation type to match in NeoFS EACL if the rule is applicable to a particular request.", "type": "string", "enum": [ "GET", @@ -884,6 +1022,7 @@ func init() { "type": "string" }, "Record": { + "description": "A single NeoFS EACL rule.", "type": "object", "required": [ "action", @@ -924,6 +1063,7 @@ func init() { } }, "Role": { + "description": "Role for target in EACL.", "type": "string", "enum": [ "USER", @@ -932,6 +1072,7 @@ func init() { ] }, "Rule": { + "description": "Container session token rule.", "type": "object", "required": [ "verb" @@ -943,9 +1084,14 @@ func init() { "verb": { "$ref": "#/definitions/Verb" } + }, + "example": { + "containerId": "6jvKJCQr6e47Yx8SsbSN3fNgzroUJVkY66Q9wqxYcAjc", + "verb": "DELETE" } }, "SearchFilter": { + "description": "Search filter to find objects.", "type": "object", "required": [ "key", @@ -962,9 +1108,15 @@ func init() { "value": { "type": "string" } + }, + "example": { + "key": "FileName", + "match": "MatchStringEqual", + "value": "object-name" } }, "SearchFilters": { + "description": "List of SearchFilter elements.", "type": "object", "required": [ "filters" @@ -976,9 +1128,24 @@ func init() { "$ref": "#/definitions/SearchFilter" } } + }, + "example": { + "filters": [ + { + "key": "FileName", + "match": "MatchCommonPrefix", + "value": "some/prefix" + }, + { + "key": "CustomAttribute", + "match": "MatchStringEqual", + "value": "tag-value" + } + ] } }, "SearchMatch": { + "description": "Search match type.", "type": "string", "enum": [ "MatchStringEqual", @@ -988,6 +1155,7 @@ func init() { ] }, "SuccessResponse": { + "description": "Success response.", "type": "object", "required": [ "success" @@ -996,9 +1164,13 @@ func init() { "success": { "type": "boolean" } + }, + "example": { + "success": true } }, "Target": { + "description": "Target to apply the ACL rule. Can be a subject's role class or a list of public keys to match.", "type": "object", "required": [ "role", @@ -1023,6 +1195,7 @@ func init() { } }, "TokenResponse": { + "description": "Base64 encoded marshaled token (for container or for object operations).", "type": "object", "required": [ "type", @@ -1041,7 +1214,7 @@ func init() { }, "example": [ { - "token": "sometoken-todo-add", + "token": "ClYKBAgCEA0aCAgDEAEiAggDGggIARACIgIIAxoICAIQAiICCAMaCAgDEAIiAggDGggIBBACIgIIAxoICAUQAiICCAMaCAgGEAIiAggDGggIBxACIgIIAxIbChk182WEDFuAqq3nssrGOaH0NK0ZhzF8bu+YGgQIaBgE", "type": "object" }, { @@ -1051,6 +1224,7 @@ func init() { ] }, "TokenType": { + "description": "Type of token.", "type": "string", "enum": [ "object", @@ -1058,6 +1232,7 @@ func init() { ] }, "Verb": { + "description": "Verb that describes the allowed container operation for token.", "type": "string", "enum": [ "PUT", @@ -1069,28 +1244,28 @@ func init() { "parameters": { "containerId": { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true }, "objectId": { "type": "string", - "description": "Base58 encoded object id", + "description": "Base58 encoded object id.", "name": "objectId", "in": "path", "required": true }, "signatureKeyParam": { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true }, "signatureParam": { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true @@ -1098,7 +1273,7 @@ func init() { "signatureScheme": { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" } @@ -1123,7 +1298,7 @@ func init() { ], "swagger": "2.0", "info": { - "description": "REST API NeoFS", + "description": "REST API for native integration with NeoFS.", "title": "REST API NeoFS", "version": "v1" }, @@ -1139,12 +1314,12 @@ func init() { "produces": [ "application/json" ], - "summary": "Form bearer token to futher requests", + "summary": "Form bearer token to further requests", "operationId": "auth", "parameters": [ { "type": "string", - "description": "Owner Id (wallet address) that will sign the token", + "description": "Owner Id (wallet address) that will sign the token.", "name": "X-Bearer-Owner-Id", "in": "header", "required": true @@ -1152,12 +1327,12 @@ func init() { { "type": "integer", "default": 100, - "description": "Token lifetime in epoch", + "description": "Token lifetime in epoch.", "name": "X-Bearer-Lifetime", "in": "header" }, { - "description": "Bearer token", + "description": "Bearer tokens to form.", "name": "tokens", "in": "body", "required": true, @@ -1171,7 +1346,7 @@ func init() { ], "responses": { "200": { - "description": "Base64 encoded stable binary marshaled bearer token", + "description": "Base64 encoded stable binary marshaled bearer token.", "schema": { "type": "array", "items": { @@ -1196,7 +1371,7 @@ func init() { "parameters": [ { "type": "string", - "description": "Base58 encoded owner id", + "description": "Base58 encoded owner id.", "name": "ownerId", "in": "query", "required": true @@ -1221,13 +1396,13 @@ func init() { ], "responses": { "200": { - "description": "Containers info", + "description": "Containers info.", "schema": { "$ref": "#/definitions/ContainerList" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1240,14 +1415,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1255,14 +1430,14 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" }, { "type": "boolean", "default": false, - "description": "Provide this parameter to register container name in NNS service", + "description": "Provide this parameter to register container name in NNS service.", "name": "name-scope-global", "in": "query" }, @@ -1278,7 +1453,7 @@ func init() { ], "responses": { "200": { - "description": "Address of uploaded objects", + "description": "Identifier of the created container.", "schema": { "type": "object", "required": [ @@ -1295,7 +1470,7 @@ func init() { } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1310,13 +1485,13 @@ func init() { "operationId": "getContainer", "responses": { "200": { - "description": "Container info", + "description": "Container info.", "schema": { "$ref": "#/definitions/ContainerInfo" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1329,14 +1504,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1344,20 +1519,20 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" } ], "responses": { "200": { - "description": "Successful deletion", + "description": "Successful deletion.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1367,7 +1542,7 @@ func init() { "parameters": [ { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true @@ -1381,13 +1556,13 @@ func init() { "operationId": "getContainerEACL", "responses": { "200": { - "description": "Container EACL information", + "description": "Container EACL information.", "schema": { "$ref": "#/definitions/Eacl" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1400,14 +1575,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1415,12 +1590,12 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" }, { - "description": "EACL for container", + "description": "EACL for container.", "name": "eacl", "in": "body", "required": true, @@ -1431,13 +1606,13 @@ func init() { ], "responses": { "200": { - "description": "Successful EACL updating", + "description": "Successful EACL updating.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1447,7 +1622,7 @@ func init() { "parameters": [ { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true @@ -1493,14 +1668,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1508,7 +1683,7 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" } @@ -1537,7 +1712,7 @@ func init() { "in": "query" }, { - "description": "Filters to search objects", + "description": "Filters to search objects.", "name": "searchFilters", "in": "body", "required": true, @@ -1564,14 +1739,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1579,13 +1754,13 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" }, { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true @@ -1600,12 +1775,14 @@ func init() { { "minimum": 0, "type": "integer", + "description": "Range offset to start reading data.", "name": "range-offset", "in": "query" }, { "minimum": 1, "type": "integer", + "description": "Length of data range.", "name": "range-length", "in": "query" }, @@ -1639,13 +1816,13 @@ func init() { "operationId": "deleteObject", "responses": { "200": { - "description": "Successful deletion", + "description": "Successful deletion.", "schema": { "$ref": "#/definitions/SuccessResponse" } }, "400": { - "description": "Bad request", + "description": "Bad request.", "schema": { "$ref": "#/definitions/ErrorResponse" } @@ -1655,14 +1832,14 @@ func init() { "parameters": [ { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true }, { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true @@ -1670,20 +1847,20 @@ func init() { { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" }, { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true }, { "type": "string", - "description": "Base58 encoded object id", + "description": "Base58 encoded object id.", "name": "objectId", "in": "path", "required": true @@ -1693,6 +1870,7 @@ func init() { }, "definitions": { "Action": { + "description": "Rule execution result action in NeoFS EACL. Either allows or denies access if the rule's filters match.", "type": "string", "enum": [ "ALLOW", @@ -1700,6 +1878,7 @@ func init() { ] }, "Address": { + "description": "Address of the object in NeoFS.", "type": "object", "required": [ "containerId", @@ -1719,6 +1898,7 @@ func init() { } }, "Attribute": { + "description": "Attribute is a pair of strings that can be attached to a container or an object.", "type": "object", "required": [ "key", @@ -1731,9 +1911,14 @@ func init() { "value": { "type": "string" } + }, + "example": { + "key": "User-Defined-Tag", + "value": "tag value" } }, "Bearer": { + "description": "Bearer token that is expected to be formed.", "type": "object", "properties": { "container": { @@ -1748,9 +1933,34 @@ func init() { "$ref": "#/definitions/Record" } } - } + }, + "example": [ + { + "name": "my-bearer-token", + "object": [ + { + "action": "ALLOW", + "filters": [], + "operation": "GET", + "targets": [ + { + "keys": [], + "role": "OTHERS" + } + ] + } + ] + }, + { + "container": { + "verb": "PUT" + }, + "name": "my token to create container" + } + ] }, "ContainerInfo": { + "description": "Information about container.", "type": "object", "required": [ "containerId", @@ -1800,12 +2010,14 @@ func init() { ], "basicAcl": "0x1fbf9fff", "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "containerName": "container", "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", "placementPolicy": "REP 2", "version": "2.11" } }, "ContainerList": { + "description": "List of containers info", "type": "object", "required": [ "size", @@ -1821,10 +2033,47 @@ func init() { "size": { "type": "integer" } + }, + "example": { + "containers": [ + { + "attribute": [ + { + "key": "Timestamp", + "value": "1648810072" + }, + { + "key": "Name", + "value": "container" + } + ], + "basicAcl": "0x1fbf9fff", + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "containerName": "container", + "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", + "placementPolicy": "REP 2", + "version": "2.11" + }, + { + "attribute": [ + { + "key": "Name", + "value": "container2" + } + ], + "basicAcl": "0x1fbf9fff", + "containerId": "FsE7HLQBBYc2WFJzuTXMcpspDEmwUxsD5YmNb2r25uUu", + "containerName": "container2", + "ownerId": "NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM", + "placementPolicy": "REP 1", + "version": "2.11" + } + ], + "size": 2 } }, "ContainerPutInfo": { - "description": "Represent request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored).", + "description": "Request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored).", "type": "object", "properties": { "attributes": { @@ -1856,6 +2105,7 @@ func init() { } }, "Eacl": { + "description": "EACL NeoFS table.", "type": "object", "required": [ "records" @@ -1871,9 +2121,32 @@ func init() { "$ref": "#/definitions/Record" } } + }, + "example": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "records": [ + { + "action": "GET", + "filters": [ + { + "headerType": "OBJECT", + "key": "FileName", + "matchType": "STRING_EQUAL", + "value": "myfile" + } + ], + "operation": "ALLOW", + "targets": [ + { + "role": "OTHERS" + } + ] + } + ] } }, "ErrorResponse": { + "description": "Error response.", "type": "object", "required": [ "type", @@ -1889,9 +2162,15 @@ func init() { "type": { "$ref": "#/definitions/ErrorType" } + }, + "example": { + "code": 1024, + "message": "incomplete object PUT by placement", + "type": "API" } }, "ErrorType": { + "description": "Error type. Allow determine source of the error.", "type": "string", "enum": [ "GW", @@ -1899,6 +2178,7 @@ func init() { ] }, "Filter": { + "description": "Filter in NeoFS EACL to check particular properties of the request or the object.", "type": "object", "required": [ "headerType", @@ -1928,6 +2208,7 @@ func init() { } }, "HeaderType": { + "description": "Enumeration of possible sources of Headers to apply filters in NeoFS EACL.", "type": "string", "enum": [ "REQUEST", @@ -1936,6 +2217,7 @@ func init() { ] }, "MatchType": { + "description": "Match type in NeoFS EACL filter.", "type": "string", "enum": [ "STRING_EQUAL", @@ -1943,6 +2225,7 @@ func init() { ] }, "ObjectBaseInfo": { + "description": "Basic object information.", "type": "object", "required": [ "address" @@ -1954,9 +2237,17 @@ func init() { "name": { "type": "string" } + }, + "example": { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd" + }, + "name": "/my/object/name" } }, "ObjectInfo": { + "description": "Object information.", "type": "object", "required": [ "containerId", @@ -2012,6 +2303,7 @@ func init() { } }, "ObjectList": { + "description": "List of objects.", "type": "object", "required": [ "size", @@ -2027,9 +2319,29 @@ func init() { "size": { "type": "integer" } + }, + "example": { + "objects": [ + { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd" + }, + "name": "/my/object/name" + }, + { + "address": { + "containerId": "5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv", + "objectId": "3GbmMWusaWgMHokWui2zDunxMTzButuQMVLbtL3cDn8s" + }, + "name": "/my/object/some/other/name" + } + ], + "size": 2 } }, "ObjectUpload": { + "description": "Request body to create object.", "type": "object", "required": [ "containerId", @@ -2065,6 +2377,7 @@ func init() { } }, "Operation": { + "description": "Request's operation type to match in NeoFS EACL if the rule is applicable to a particular request.", "type": "string", "enum": [ "GET", @@ -2080,6 +2393,7 @@ func init() { "type": "string" }, "Record": { + "description": "A single NeoFS EACL rule.", "type": "object", "required": [ "action", @@ -2120,6 +2434,7 @@ func init() { } }, "Role": { + "description": "Role for target in EACL.", "type": "string", "enum": [ "USER", @@ -2128,6 +2443,7 @@ func init() { ] }, "Rule": { + "description": "Container session token rule.", "type": "object", "required": [ "verb" @@ -2139,9 +2455,14 @@ func init() { "verb": { "$ref": "#/definitions/Verb" } + }, + "example": { + "containerId": "6jvKJCQr6e47Yx8SsbSN3fNgzroUJVkY66Q9wqxYcAjc", + "verb": "DELETE" } }, "SearchFilter": { + "description": "Search filter to find objects.", "type": "object", "required": [ "key", @@ -2158,9 +2479,15 @@ func init() { "value": { "type": "string" } + }, + "example": { + "key": "FileName", + "match": "MatchStringEqual", + "value": "object-name" } }, "SearchFilters": { + "description": "List of SearchFilter elements.", "type": "object", "required": [ "filters" @@ -2172,9 +2499,24 @@ func init() { "$ref": "#/definitions/SearchFilter" } } + }, + "example": { + "filters": [ + { + "key": "FileName", + "match": "MatchCommonPrefix", + "value": "some/prefix" + }, + { + "key": "CustomAttribute", + "match": "MatchStringEqual", + "value": "tag-value" + } + ] } }, "SearchMatch": { + "description": "Search match type.", "type": "string", "enum": [ "MatchStringEqual", @@ -2184,6 +2526,7 @@ func init() { ] }, "SuccessResponse": { + "description": "Success response.", "type": "object", "required": [ "success" @@ -2192,9 +2535,13 @@ func init() { "success": { "type": "boolean" } + }, + "example": { + "success": true } }, "Target": { + "description": "Target to apply the ACL rule. Can be a subject's role class or a list of public keys to match.", "type": "object", "required": [ "role", @@ -2219,6 +2566,7 @@ func init() { } }, "TokenResponse": { + "description": "Base64 encoded marshaled token (for container or for object operations).", "type": "object", "required": [ "type", @@ -2237,7 +2585,7 @@ func init() { }, "example": [ { - "token": "sometoken-todo-add", + "token": "ClYKBAgCEA0aCAgDEAEiAggDGggIARACIgIIAxoICAIQAiICCAMaCAgDEAIiAggDGggIBBACIgIIAxoICAUQAiICCAMaCAgGEAIiAggDGggIBxACIgIIAxIbChk182WEDFuAqq3nssrGOaH0NK0ZhzF8bu+YGgQIaBgE", "type": "object" }, { @@ -2247,6 +2595,7 @@ func init() { ] }, "TokenType": { + "description": "Type of token.", "type": "string", "enum": [ "object", @@ -2254,6 +2603,7 @@ func init() { ] }, "Verb": { + "description": "Verb that describes the allowed container operation for token.", "type": "string", "enum": [ "PUT", @@ -2265,28 +2615,28 @@ func init() { "parameters": { "containerId": { "type": "string", - "description": "Base58 encoded container id", + "description": "Base58 encoded container id.", "name": "containerId", "in": "path", "required": true }, "objectId": { "type": "string", - "description": "Base58 encoded object id", + "description": "Base58 encoded object id.", "name": "objectId", "in": "path", "required": true }, "signatureKeyParam": { "type": "string", - "description": "Hex encoded the public part of the key that signed the bearer token", + "description": "Hex encoded the public part of the key that signed the bearer token.", "name": "X-Bearer-Signature-Key", "in": "header", "required": true }, "signatureParam": { "type": "string", - "description": "Base64 encoded signature for bearer token", + "description": "Base64 encoded signature for bearer token.", "name": "X-Bearer-Signature", "in": "header", "required": true @@ -2294,7 +2644,7 @@ func init() { "signatureScheme": { "type": "boolean", "default": false, - "description": "Use wallect connect signature scheme or not", + "description": "Use wallet connect signature scheme or native NeoFS signature.", "name": "walletConnect", "in": "query" } diff --git a/gen/restapi/operations/auth.go b/gen/restapi/operations/auth.go index 8433af6..2c1acdd 100644 --- a/gen/restapi/operations/auth.go +++ b/gen/restapi/operations/auth.go @@ -31,7 +31,7 @@ func NewAuth(ctx *middleware.Context, handler AuthHandler) *Auth { /* Auth swagger:route POST /auth auth -Form bearer token to futher requests +Form bearer token to further requests */ type Auth struct { diff --git a/gen/restapi/operations/auth_parameters.go b/gen/restapi/operations/auth_parameters.go index a380581..9bdf03f 100644 --- a/gen/restapi/operations/auth_parameters.go +++ b/gen/restapi/operations/auth_parameters.go @@ -43,17 +43,17 @@ type AuthParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Token lifetime in epoch + /*Token lifetime in epoch. In: header Default: 100 */ XBearerLifetime *int64 - /*Owner Id (wallet address) that will sign the token + /*Owner Id (wallet address) that will sign the token. Required: true In: header */ XBearerOwnerID string - /*Bearer token + /*Bearer tokens to form. Required: true In: body */ diff --git a/gen/restapi/operations/auth_responses.go b/gen/restapi/operations/auth_responses.go index d3d9d29..5178989 100644 --- a/gen/restapi/operations/auth_responses.go +++ b/gen/restapi/operations/auth_responses.go @@ -16,7 +16,7 @@ import ( // AuthOKCode is the HTTP code returned for type AuthOK const AuthOKCode int = 200 -/*AuthOK Base64 encoded stable binary marshaled bearer token +/*AuthOK Base64 encoded stable binary marshaled bearer token. swagger:response authOK */ diff --git a/gen/restapi/operations/delete_container_parameters.go b/gen/restapi/operations/delete_container_parameters.go index 9fc7e54..3d79698 100644 --- a/gen/restapi/operations/delete_container_parameters.go +++ b/gen/restapi/operations/delete_container_parameters.go @@ -40,22 +40,22 @@ type DeleteContainerParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ XBearerSignatureKey string - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ ContainerID string - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/delete_container_responses.go b/gen/restapi/operations/delete_container_responses.go index 4b5c2de..0880917 100644 --- a/gen/restapi/operations/delete_container_responses.go +++ b/gen/restapi/operations/delete_container_responses.go @@ -16,7 +16,7 @@ import ( // DeleteContainerOKCode is the HTTP code returned for type DeleteContainerOK const DeleteContainerOKCode int = 200 -/*DeleteContainerOK Successful deletion +/*DeleteContainerOK Successful deletion. swagger:response deleteContainerOK */ @@ -60,7 +60,7 @@ func (o *DeleteContainerOK) WriteResponse(rw http.ResponseWriter, producer runti // DeleteContainerBadRequestCode is the HTTP code returned for type DeleteContainerBadRequest const DeleteContainerBadRequestCode int = 400 -/*DeleteContainerBadRequest Bad request +/*DeleteContainerBadRequest Bad request. swagger:response deleteContainerBadRequest */ diff --git a/gen/restapi/operations/delete_object_parameters.go b/gen/restapi/operations/delete_object_parameters.go index 5625b84..3da8072 100644 --- a/gen/restapi/operations/delete_object_parameters.go +++ b/gen/restapi/operations/delete_object_parameters.go @@ -40,27 +40,27 @@ type DeleteObjectParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ XBearerSignatureKey string - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ ContainerID string - /*Base58 encoded object id + /*Base58 encoded object id. Required: true In: path */ ObjectID string - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/delete_object_responses.go b/gen/restapi/operations/delete_object_responses.go index c21c10b..2a84d29 100644 --- a/gen/restapi/operations/delete_object_responses.go +++ b/gen/restapi/operations/delete_object_responses.go @@ -16,7 +16,7 @@ import ( // DeleteObjectOKCode is the HTTP code returned for type DeleteObjectOK const DeleteObjectOKCode int = 200 -/*DeleteObjectOK Successful deletion +/*DeleteObjectOK Successful deletion. swagger:response deleteObjectOK */ @@ -60,7 +60,7 @@ func (o *DeleteObjectOK) WriteResponse(rw http.ResponseWriter, producer runtime. // DeleteObjectBadRequestCode is the HTTP code returned for type DeleteObjectBadRequest const DeleteObjectBadRequestCode int = 400 -/*DeleteObjectBadRequest Bad request +/*DeleteObjectBadRequest Bad request. swagger:response deleteObjectBadRequest */ diff --git a/gen/restapi/operations/get_container_e_acl_parameters.go b/gen/restapi/operations/get_container_e_acl_parameters.go index 04a1366..278b276 100644 --- a/gen/restapi/operations/get_container_e_acl_parameters.go +++ b/gen/restapi/operations/get_container_e_acl_parameters.go @@ -30,7 +30,7 @@ type GetContainerEACLParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ diff --git a/gen/restapi/operations/get_container_e_acl_responses.go b/gen/restapi/operations/get_container_e_acl_responses.go index 87eb5bd..ae82d5b 100644 --- a/gen/restapi/operations/get_container_e_acl_responses.go +++ b/gen/restapi/operations/get_container_e_acl_responses.go @@ -16,7 +16,7 @@ import ( // GetContainerEACLOKCode is the HTTP code returned for type GetContainerEACLOK const GetContainerEACLOKCode int = 200 -/*GetContainerEACLOK Container EACL information +/*GetContainerEACLOK Container EACL information. swagger:response getContainerEAclOK */ @@ -60,7 +60,7 @@ func (o *GetContainerEACLOK) WriteResponse(rw http.ResponseWriter, producer runt // GetContainerEACLBadRequestCode is the HTTP code returned for type GetContainerEACLBadRequest const GetContainerEACLBadRequestCode int = 400 -/*GetContainerEACLBadRequest Bad request +/*GetContainerEACLBadRequest Bad request. swagger:response getContainerEAclBadRequest */ diff --git a/gen/restapi/operations/get_container_parameters.go b/gen/restapi/operations/get_container_parameters.go index 5082ea9..4e9bd30 100644 --- a/gen/restapi/operations/get_container_parameters.go +++ b/gen/restapi/operations/get_container_parameters.go @@ -30,7 +30,7 @@ type GetContainerParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ diff --git a/gen/restapi/operations/get_container_responses.go b/gen/restapi/operations/get_container_responses.go index 307fe0d..891dddb 100644 --- a/gen/restapi/operations/get_container_responses.go +++ b/gen/restapi/operations/get_container_responses.go @@ -16,7 +16,7 @@ import ( // GetContainerOKCode is the HTTP code returned for type GetContainerOK const GetContainerOKCode int = 200 -/*GetContainerOK Container info +/*GetContainerOK Container info. swagger:response getContainerOK */ @@ -60,7 +60,7 @@ func (o *GetContainerOK) WriteResponse(rw http.ResponseWriter, producer runtime. // GetContainerBadRequestCode is the HTTP code returned for type GetContainerBadRequest const GetContainerBadRequestCode int = 400 -/*GetContainerBadRequest Bad request +/*GetContainerBadRequest Bad request. swagger:response getContainerBadRequest */ diff --git a/gen/restapi/operations/get_object_info_parameters.go b/gen/restapi/operations/get_object_info_parameters.go index e904089..5e944c5 100644 --- a/gen/restapi/operations/get_object_info_parameters.go +++ b/gen/restapi/operations/get_object_info_parameters.go @@ -44,17 +44,17 @@ type GetObjectInfoParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ XBearerSignatureKey string - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ @@ -68,22 +68,22 @@ type GetObjectInfoParams struct { Default: 4.194304e+06 */ MaxPayloadSize *int64 - /*Base58 encoded object id + /*Base58 encoded object id. Required: true In: path */ ObjectID string - /* + /*Length of data range. Minimum: 1 In: query */ RangeLength *int64 - /* + /*Range offset to start reading data. Minimum: 0 In: query */ RangeOffset *int64 - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/list_containers_parameters.go b/gen/restapi/operations/list_containers_parameters.go index 2ab1a7b..f314d1f 100644 --- a/gen/restapi/operations/list_containers_parameters.go +++ b/gen/restapi/operations/list_containers_parameters.go @@ -56,7 +56,7 @@ type ListContainersParams struct { Default: 0 */ Offset *int64 - /*Base58 encoded owner id + /*Base58 encoded owner id. Required: true In: query */ diff --git a/gen/restapi/operations/list_containers_responses.go b/gen/restapi/operations/list_containers_responses.go index 0bab3e7..6c91526 100644 --- a/gen/restapi/operations/list_containers_responses.go +++ b/gen/restapi/operations/list_containers_responses.go @@ -16,7 +16,7 @@ import ( // ListContainersOKCode is the HTTP code returned for type ListContainersOK const ListContainersOKCode int = 200 -/*ListContainersOK Containers info +/*ListContainersOK Containers info. swagger:response listContainersOK */ @@ -60,7 +60,7 @@ func (o *ListContainersOK) WriteResponse(rw http.ResponseWriter, producer runtim // ListContainersBadRequestCode is the HTTP code returned for type ListContainersBadRequest const ListContainersBadRequestCode int = 400 -/*ListContainersBadRequest Bad request +/*ListContainersBadRequest Bad request. swagger:response listContainersBadRequest */ diff --git a/gen/restapi/operations/neofs_rest_gw_api.go b/gen/restapi/operations/neofs_rest_gw_api.go index 3dd8021..57684e1 100644 --- a/gen/restapi/operations/neofs_rest_gw_api.go +++ b/gen/restapi/operations/neofs_rest_gw_api.go @@ -87,7 +87,7 @@ func NewNeofsRestGwAPI(spec *loads.Document) *NeofsRestGwAPI { } } -/*NeofsRestGwAPI REST API NeoFS */ +/*NeofsRestGwAPI REST API for native integration with NeoFS. */ type NeofsRestGwAPI struct { spec *loads.Document context *middleware.Context diff --git a/gen/restapi/operations/put_container_e_acl_parameters.go b/gen/restapi/operations/put_container_e_acl_parameters.go index b1ef4a0..06de0dc 100644 --- a/gen/restapi/operations/put_container_e_acl_parameters.go +++ b/gen/restapi/operations/put_container_e_acl_parameters.go @@ -44,27 +44,27 @@ type PutContainerEACLParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ XBearerSignatureKey string - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ ContainerID string - /*EACL for container + /*EACL for container. Required: true In: body */ Eacl *models.Eacl - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/put_container_e_acl_responses.go b/gen/restapi/operations/put_container_e_acl_responses.go index 396f891..0fb47cc 100644 --- a/gen/restapi/operations/put_container_e_acl_responses.go +++ b/gen/restapi/operations/put_container_e_acl_responses.go @@ -16,7 +16,7 @@ import ( // PutContainerEACLOKCode is the HTTP code returned for type PutContainerEACLOK const PutContainerEACLOKCode int = 200 -/*PutContainerEACLOK Successful EACL updating +/*PutContainerEACLOK Successful EACL updating. swagger:response putContainerEAclOK */ @@ -60,7 +60,7 @@ func (o *PutContainerEACLOK) WriteResponse(rw http.ResponseWriter, producer runt // PutContainerEACLBadRequestCode is the HTTP code returned for type PutContainerEACLBadRequest const PutContainerEACLBadRequestCode int = 400 -/*PutContainerEACLBadRequest Bad request +/*PutContainerEACLBadRequest Bad request. swagger:response putContainerEAclBadRequest */ diff --git a/gen/restapi/operations/put_container_parameters.go b/gen/restapi/operations/put_container_parameters.go index 718aaa6..aa9c423 100644 --- a/gen/restapi/operations/put_container_parameters.go +++ b/gen/restapi/operations/put_container_parameters.go @@ -47,12 +47,12 @@ type PutContainerParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ @@ -62,12 +62,12 @@ type PutContainerParams struct { In: body */ Container *models.ContainerPutInfo - /*Provide this parameter to register container name in NNS service + /*Provide this parameter to register container name in NNS service. In: query Default: false */ NameScopeGlobal *bool - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/put_container_responses.go b/gen/restapi/operations/put_container_responses.go index e244dc6..2f43fa5 100644 --- a/gen/restapi/operations/put_container_responses.go +++ b/gen/restapi/operations/put_container_responses.go @@ -16,7 +16,7 @@ import ( // PutContainerOKCode is the HTTP code returned for type PutContainerOK const PutContainerOKCode int = 200 -/*PutContainerOK Address of uploaded objects +/*PutContainerOK Identifier of the created container. swagger:response putContainerOK */ @@ -60,7 +60,7 @@ func (o *PutContainerOK) WriteResponse(rw http.ResponseWriter, producer runtime. // PutContainerBadRequestCode is the HTTP code returned for type PutContainerBadRequest const PutContainerBadRequestCode int = 400 -/*PutContainerBadRequest Bad request +/*PutContainerBadRequest Bad request. swagger:response putContainerBadRequest */ diff --git a/gen/restapi/operations/put_object_parameters.go b/gen/restapi/operations/put_object_parameters.go index 80eb093..5d9c0cb 100644 --- a/gen/restapi/operations/put_object_parameters.go +++ b/gen/restapi/operations/put_object_parameters.go @@ -44,12 +44,12 @@ type PutObjectParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ @@ -59,7 +59,7 @@ type PutObjectParams struct { In: body */ Object *models.ObjectUpload - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/gen/restapi/operations/search_objects_parameters.go b/gen/restapi/operations/search_objects_parameters.go index 5371497..2828c1f 100644 --- a/gen/restapi/operations/search_objects_parameters.go +++ b/gen/restapi/operations/search_objects_parameters.go @@ -51,17 +51,17 @@ type SearchObjectsParams struct { // HTTP Request Object HTTPRequest *http.Request `json:"-"` - /*Base64 encoded signature for bearer token + /*Base64 encoded signature for bearer token. Required: true In: header */ XBearerSignature string - /*Hex encoded the public part of the key that signed the bearer token + /*Hex encoded the public part of the key that signed the bearer token. Required: true In: header */ XBearerSignatureKey string - /*Base58 encoded container id + /*Base58 encoded container id. Required: true In: path */ @@ -79,12 +79,12 @@ type SearchObjectsParams struct { Default: 0 */ Offset *int64 - /*Filters to search objects + /*Filters to search objects. Required: true In: body */ SearchFilters *models.SearchFilters - /*Use wallect connect signature scheme or not + /*Use wallet connect signature scheme or native NeoFS signature. In: query Default: false */ diff --git a/spec/rest.yaml b/spec/rest.yaml index baaaec1..b72fb47 100644 --- a/spec/rest.yaml +++ b/spec/rest.yaml @@ -1,14 +1,13 @@ swagger: "2.0" info: title: REST API NeoFS - description: REST API NeoFS + description: REST API for native integration with NeoFS. version: v1 host: localhost:8090 basePath: /v1 schemes: - http -# - https securityDefinitions: BearerAuth: @@ -24,19 +23,19 @@ parameters: signatureParam: in: header name: X-Bearer-Signature - description: Base64 encoded signature for bearer token + description: Base64 encoded signature for bearer token. type: string required: true signatureKeyParam: in: header name: X-Bearer-Signature-Key - description: Hex encoded the public part of the key that signed the bearer token + description: Hex encoded the public part of the key that signed the bearer token. type: string required: true signatureScheme: in: query name: walletConnect - description: Use wallect connect signature scheme or not + description: Use wallet connect signature scheme or native NeoFS signature. type: boolean default: false containerId: @@ -44,35 +43,35 @@ parameters: name: containerId type: string required: true - description: Base58 encoded container id + description: Base58 encoded container id. objectId: in: path name: objectId type: string required: true - description: Base58 encoded object id + description: Base58 encoded object id. paths: /auth: post: operationId: auth - summary: Form bearer token to futher requests + summary: Form bearer token to further requests security: [ ] parameters: - in: header name: X-Bearer-Owner-Id - description: Owner Id (wallet address) that will sign the token + description: Owner Id (wallet address) that will sign the token. type: string required: true - in: header - description: Token lifetime in epoch + description: Token lifetime in epoch. name: X-Bearer-Lifetime type: integer default: 100 - in: body name: tokens required: true - description: Bearer token + description: Bearer tokens to form. schema: type: array items: @@ -83,7 +82,7 @@ paths: - application/json responses: 200: - description: Base64 encoded stable binary marshaled bearer token + description: Base64 encoded stable binary marshaled bearer token. schema: type: array items: @@ -148,7 +147,7 @@ paths: - in: body required: true name: searchFilters - description: Filters to search objects + description: Filters to search objects. schema: $ref: '#/definitions/SearchFilters' responses: @@ -176,10 +175,12 @@ paths: name: range-offset type: integer minimum: 0 + description: Range offset to start reading data. - in: query name: range-length type: integer minimum: 1 + description: Length of data range. - in: query name: max-payload-size type: integer @@ -203,11 +204,11 @@ paths: summary: Remove object from NeoFS responses: 200: - description: Successful deletion + description: Successful deletion. schema: $ref: '#/definitions/SuccessResponse' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' @@ -221,7 +222,7 @@ paths: - $ref: '#/parameters/signatureScheme' - in: query name: name-scope-global - description: Provide this parameter to register container name in NNS service + description: Provide this parameter to register container name in NNS service. type: boolean default: false - in: body @@ -232,7 +233,7 @@ paths: $ref: '#/definitions/ContainerPutInfo' responses: 200: - description: Address of uploaded objects + description: Identifier of the created container. schema: type: object properties: @@ -243,7 +244,7 @@ paths: example: containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' get: @@ -255,7 +256,7 @@ paths: name: ownerId required: true type: string - description: Base58 encoded owner id + description: Base58 encoded owner id. - in: query name: offset type: integer @@ -271,11 +272,11 @@ paths: description: The numbers of containers to return. responses: 200: - description: Containers info + description: Containers info. schema: $ref: '#/definitions/ContainerList' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' @@ -288,11 +289,11 @@ paths: security: [ ] responses: 200: - description: Container info + description: Container info. schema: $ref: '#/definitions/ContainerInfo' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' delete: @@ -304,11 +305,11 @@ paths: - $ref: '#/parameters/signatureScheme' responses: 200: - description: Successful deletion + description: Successful deletion. schema: $ref: '#/definitions/SuccessResponse' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' /containers/{containerId}/eacl: @@ -324,16 +325,16 @@ paths: - in: body name: eacl required: true - description: EACL for container + description: EACL for container. schema: $ref: '#/definitions/Eacl' responses: 200: - description: Successful EACL updating + description: Successful EACL updating. schema: $ref: '#/definitions/SuccessResponse' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' get: @@ -342,16 +343,17 @@ paths: security: [ ] responses: 200: - description: Container EACL information + description: Container EACL information. schema: $ref: '#/definitions/Eacl' 400: - description: Bad request + description: Bad request. schema: $ref: '#/definitions/ErrorResponse' definitions: Bearer: + description: Bearer token that is expected to be formed. type: object properties: name: @@ -362,7 +364,20 @@ definitions: $ref: '#/definitions/Record' container: $ref: '#/definitions/Rule' + example: + - name: my-bearer-token + object: + - operation: GET + action: ALLOW + filters: [ ] + targets: + - role: OTHERS + keys: [ ] + - name: "my token to create container" + container: + verb: PUT Record: + description: A single NeoFS EACL rule. type: object properties: action: @@ -390,11 +405,13 @@ definitions: - role: OTHERS keys: [ ] Action: + description: Rule execution result action in NeoFS EACL. Either allows or denies access if the rule's filters match. type: string enum: - ALLOW - DENY Operation: + description: Request's operation type to match in NeoFS EACL if the rule is applicable to a particular request. type: string enum: - GET @@ -405,6 +422,7 @@ definitions: - RANGE - RANGEHASH Filter: + description: Filter in NeoFS EACL to check particular properties of the request or the object. type: object properties: headerType: @@ -426,17 +444,20 @@ definitions: key: FileName value: myfile HeaderType: + description: Enumeration of possible sources of Headers to apply filters in NeoFS EACL. type: string enum: - REQUEST - OBJECT - SERVICE MatchType: + description: Match type in NeoFS EACL filter. type: string enum: - STRING_EQUAL - STRING_NOT_EQUAL Target: + description: Target to apply the ACL rule. Can be a subject's role class or a list of public keys to match. type: object properties: role: @@ -453,12 +474,14 @@ definitions: keys: - 021dc56fc6d81d581ae7605a8e00e0e0bab6cbad566a924a527339475a97a8e38e Role: + description: Role for target in EACL. type: string enum: - USER - SYSTEM - OTHERS Rule: + description: Container session token rule. type: object properties: verb: @@ -467,13 +490,18 @@ definitions: type: string required: - verb + example: + verb: DELETE + containerId: 6jvKJCQr6e47Yx8SsbSN3fNgzroUJVkY66Q9wqxYcAjc Verb: + description: Verb that describes the allowed container operation for token. type: string enum: - PUT - DELETE - SETEACL TokenResponse: + description: Base64 encoded marshaled token (for container or for object operations). type: object properties: name: @@ -487,16 +515,17 @@ definitions: - token example: - type: object - token: sometoken-todo-add + token: ClYKBAgCEA0aCAgDEAEiAggDGggIARACIgIIAxoICAIQAiICCAMaCAgDEAIiAggDGggIBBACIgIIAxoICAUQAiICCAMaCAgGEAIiAggDGggIBxACIgIIAxIbChk182WEDFuAqq3nssrGOaH0NK0ZhzF8bu+YGgQIaBgE - type: container token: ChCpanIBJCpJuJz42KOmGMSnEhsKGTWquaX2Lq6GhhO4faOYkLD0f9WkXuYJlq4aBAhnGAMiIQJgFcIEghQB5lq3AJZOVswInwc1IGhlQ7NCUh4DFO3UATIECAEQAQ== TokenType: + description: Type of token. type: string enum: - object - container ContainerPutInfo: - description: Represent request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored). + description: Request body to create container. To specify container name use appropriate property (name provided in attributes will be ignored). type: object properties: containerName: @@ -517,6 +546,7 @@ definitions: - key: Custom-Attribute value: value ContainerInfo: + description: Information about container. type: object properties: containerId: @@ -545,6 +575,7 @@ definitions: - attributes example: containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + containerName: container version: "2.11" ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM basicAcl: "0x1fbf9fff" @@ -555,6 +586,7 @@ definitions: - key: Name value: container ContainerList: + description: List of containers info type: object properties: size: @@ -566,7 +598,31 @@ definitions: required: - size - containers + example: + size: 2 + containers: + - containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + containerName: container + version: "2.11" + ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM + basicAcl: "0x1fbf9fff" + placementPolicy: "REP 2" + attribute: + - key: Timestamp + value: "1648810072" + - key: Name + value: container + - containerId: FsE7HLQBBYc2WFJzuTXMcpspDEmwUxsD5YmNb2r25uUu + containerName: container2 + version: "2.11" + ownerId: NbUgTSFvPmsRxmGeWpuuGeJUoRoi6PErcM + basicAcl: "0x1fbf9fff" + placementPolicy: "REP 1" + attribute: + - key: Name + value: container2 SearchFilters: + description: List of SearchFilter elements. type: object properties: filters: @@ -575,7 +631,16 @@ definitions: $ref: '#/definitions/SearchFilter' required: - filters + example: + filters: + - key: FileName + value: some/prefix + match: MatchCommonPrefix + - key: CustomAttribute + value: tag-value + match: MatchStringEqual SearchFilter: + description: Search filter to find objects. type: object properties: key: @@ -588,7 +653,12 @@ definitions: - key - value - match + example: + key: FileName + value: object-name + match: MatchStringEqual SearchMatch: + description: Search match type. type: string enum: - MatchStringEqual @@ -596,6 +666,7 @@ definitions: - MatchNotPresent - MatchCommonPrefix ObjectList: + description: List of objects. type: object properties: size: @@ -607,7 +678,19 @@ definitions: required: - size - objects + example: + size: 2 + objects: + - name: "/my/object/name" + address: + objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + - name: "/my/object/some/other/name" + address: + objectId: 3GbmMWusaWgMHokWui2zDunxMTzButuQMVLbtL3cDn8s + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv ObjectBaseInfo: + description: Basic object information. type: object properties: address: @@ -616,7 +699,13 @@ definitions: type: string required: - address + example: + name: "/my/object/name" + address: + objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv ObjectUpload: + description: Request body to create object. type: object properties: containerId: @@ -640,6 +729,7 @@ definitions: - key: User-Attribute value: some-value ObjectInfo: + description: Object information. type: object properties: containerId: @@ -678,6 +768,7 @@ definitions: - key: Name value: object Address: + description: Address of the object in NeoFS. type: object properties: containerId: @@ -691,6 +782,7 @@ definitions: objectId: 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv Eacl: + description: EACL NeoFS table. type: object properties: containerId: @@ -702,7 +794,20 @@ definitions: $ref: '#/definitions/Record' required: - records + example: + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + records: + - action: GET + operation: ALLOW + filters: + - headerType: OBJECT + matchType: STRING_EQUAL + key: FileName + value: myfile + targets: + - role: OTHERS Attribute: + description: Attribute is a pair of strings that can be attached to a container or an object. type: object properties: key: @@ -712,14 +817,19 @@ definitions: required: - key - value + example: + key: "User-Defined-Tag" + value: "tag value" Principal: type: string ErrorType: + description: Error type. Allow determine source of the error. type: string enum: - GW - API ErrorResponse: + description: Error response. type: object properties: type: @@ -731,10 +841,17 @@ definitions: required: - type - message + example: + type: API + code: 1024 + message: "incomplete object PUT by placement" SuccessResponse: + description: Success response. type: object properties: success: type: boolean required: - success + example: + success: true