[#24] Update examples and description in spec

Signed-off-by: Denis Kirillov <denis@nspcc.ru>

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

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

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 {

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 {

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 {

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 {

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

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 {

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 {

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

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

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

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

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 {

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

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 {

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

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

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

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

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 {

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 {

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 {

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

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 {

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

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 {

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

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

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

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 {

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
 	*/

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
 */

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
 	*/

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
 */

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
 	*/

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
 */

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
 	*/

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
 */

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
 	*/

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
 */

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
 	*/

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
 	*/

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
 */

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

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
 	*/

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
 */

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
 	*/

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
 */

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
 	*/

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
 	*/

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