diff --git a/handlers/api.go b/handlers/api.go
index 58c4f39..41b15af 100644
--- a/handlers/api.go
+++ b/handlers/api.go
@@ -53,6 +53,8 @@ const (
// ContextKeyRequestID is the ContextKey for RequestID.
ContextKeyRequestID ContextKey = "requestID"
+
+ docPrefix = "/doc"
)
// New creates a new API using specified logger, connection pool and other parameters.
@@ -99,7 +101,7 @@ func (a *API) Configure(api *operations.NeofsRestGwAPI) http.Handler {
api.ServerShutdown = func() {}
- return a.setupGlobalMiddleware(api.Serve(setupMiddlewares))
+ return a.setupGlobalMiddleware(a.docMiddleware(api.Serve(setupMiddlewares)))
}
// The middleware configuration is for the handler executors. These do not apply to the swagger.json document.
@@ -123,6 +125,18 @@ func (a *API) setupGlobalMiddleware(handler http.Handler) http.Handler {
})
}
+func (a *API) docMiddleware(handler http.Handler) http.Handler {
+ fh := http.StripPrefix(docPrefix, http.FileServer(http.Dir("static/doc")))
+
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if strings.HasPrefix(r.URL.Path, docPrefix) {
+ fh.ServeHTTP(w, r)
+ } else {
+ handler.ServeHTTP(w, r)
+ }
+ })
+}
+
func (a *API) logAndGetErrorResponse(msg string, err error, fields ...zap.Field) *models.ErrorResponse {
fields = append(fields, zap.Error(err))
a.log.Error(msg, fields...)
diff --git a/static/doc/acl-basic.svg b/static/doc/acl-basic.svg
new file mode 100644
index 0000000..0b83e89
--- /dev/null
+++ b/static/doc/acl-basic.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/static/doc/doc.md b/static/doc/doc.md
new file mode 100644
index 0000000..f143f55
--- /dev/null
+++ b/static/doc/doc.md
@@ -0,0 +1,78 @@
+
+# neofs-rest-gw
+
+NeoFS REST Gateway bridges NeoFS internal protocol and REST API server.
+
+### Open API specification
+
+See full [API spec](/v1/docs).
+
+### Basic concept
+
+Using this API you can interact with NeoFS nodes and manage containers and objects.
+
+#### Container
+
+To create container you must provide `PlacementPolicy` and `BasicACL`.
+
+##### Placement policy
+
+Placement policy allows you control where and how container (and its object) is stored.
+For example, you want to store 3 copy of every object, so you can use the following policy:
+
+```
+REP 3
+```
+
+[More about policy](https://github.com/nspcc-dev/neofs-spec/blob/7ae698ebbe68c689cab2aba518312e7d3eea403c/01-arch/02-policy.md).
+
+##### Basic ACL
+
+Basic ACL is a part of the container structure, and it is always created simultaneously with the container.
+Therefore, it is never subject to any changes. It is a 32-bit integer with a bit field in the following format:
+
+
+
+| Symbol | Meaning | Description |
+|--------|:--------|------------------------------------------------------------------------------------------------|
+| **B** | Bearer | Allows using Bear Token ACL rules to replace eACL rules |
+| **U** | User | The owner of the container identified by the public key linked to the container |
+| **S** | System | Inner Ring and/or container nodes in the current version of network map |
+| | | IR nodes can only perform `GetRangeHash`, `Head`, and `Search` necessary for data audit. |
+| | | Container nodes can only do things required for the replication. |
+| **O** | Others | Clients that do not match any of the categories above |
+| **F** | Final | Flag denying Extended ACL. If set, Basic ACL check is final, Extended ACL is ignored |
+| **X** | Sticky | Flag denying different owners of the request and the object |
+| | | If set, object in `Put` request must have one `Owner` and be signed with the same signature |
+| | | If not set, the object must be correct but can be of any owner. |
+| | | The nodes falling for `SYSTEM` role are exception from this rule. For them the bit is ignored. |
+| **0** | Deny | Denies operation of the identified category |
+| **1** | Allow | Allows operation of the identified category |
+
+To upload objects with bearer token your container must have Bearer bits set.
+For example, you can use `0x0FBFBFFF` or predefined `eacl-public-read-write` values.
+
+Also don't forget set appropriate eACL to restrict your container.
+
+[More about ACL](https://github.com/nspcc-dev/neofs-spec/blob/4f8d945dfbd2a313ebd406746cf38b9de9da6038/01-arch/07-acl.md).
+
+#### Object
+To create object you must provide `containerId` and `fileName`.
+Additionally, you can provide `payload` (base64 encoded data) and `attributes`.
+
+Attribute is key value data that is stored with object. Key and value must be in utf8 format and must not be empty.
+
+Valid attribute:
+* `MyAttribute: 'some value'`
+
+Invalid attribute:
+* `MyAttribute: ''`
+
+Also, you can use this attribute to further object searching.
+
+### Status codes
+
+More about NeoFS status code you can
+find [here](https://github.com/nspcc-dev/neofs-spec/blob/master/20-api-v2/status.md).
+
+
diff --git a/static/doc/index.html b/static/doc/index.html
new file mode 100644
index 0000000..a630791
--- /dev/null
+++ b/static/doc/index.html
@@ -0,0 +1,15 @@
+
+
+
+
+ NeoFS REST GW
+
+
+
+
+
+
+
+
+
+
+
+| Symbol | Meaning | Description |
+|--------|:--------|------------------------------------------------------------------------------------------------|
+| **B** | Bearer | Allows using Bear Token ACL rules to replace eACL rules |
+| **U** | User | The owner of the container identified by the public key linked to the container |
+| **S** | System | Inner Ring and/or container nodes in the current version of network map |
+| | | IR nodes can only perform `GetRangeHash`, `Head`, and `Search` necessary for data audit. |
+| | | Container nodes can only do things required for the replication. |
+| **O** | Others | Clients that do not match any of the categories above |
+| **F** | Final | Flag denying Extended ACL. If set, Basic ACL check is final, Extended ACL is ignored |
+| **X** | Sticky | Flag denying different owners of the request and the object |
+| | | If set, object in `Put` request must have one `Owner` and be signed with the same signature |
+| | | If not set, the object must be correct but can be of any owner. |
+| | | The nodes falling for `SYSTEM` role are exception from this rule. For them the bit is ignored. |
+| **0** | Deny | Denies operation of the identified category |
+| **1** | Allow | Allows operation of the identified category |
+
+To upload objects with bearer token your container must have Bearer bits set.
+For example, you can use `0x0FBFBFFF` or predefined `eacl-public-read-write` values.
+
+Also don't forget set appropriate eACL to restrict your container.
+
+[More about ACL](https://github.com/nspcc-dev/neofs-spec/blob/4f8d945dfbd2a313ebd406746cf38b9de9da6038/01-arch/07-acl.md).
+
+#### Object
+To create object you must provide `containerId` and `fileName`.
+Additionally, you can provide `payload` (base64 encoded data) and `attributes`.
+
+Attribute is key value data that is stored with object. Key and value must be in utf8 format and must not be empty.
+
+Valid attribute:
+* `MyAttribute: 'some value'`
+
+Invalid attribute:
+* `MyAttribute: ''`
+
+Also, you can use this attribute to further object searching.
+
+### Status codes
+
+More about NeoFS status code you can
+find [here](https://github.com/nspcc-dev/neofs-spec/blob/master/20-api-v2/status.md).
+
+
diff --git a/static/doc/index.html b/static/doc/index.html
new file mode 100644
index 0000000..a630791
--- /dev/null
+++ b/static/doc/index.html
@@ -0,0 +1,15 @@
+
+
+
+
+