[#15] Add docs

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

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...)

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:
+
+<img src="doc/acl-basic.svg" alt="acl-basic">
+
+| 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).
+
+

static/doc/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>NeoFS REST GW</title>
+</head>
+
+<body>
+
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-loader.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/gh/zerodevx/zero-md@1/src/zero-md.min.js"></script>
+<zero-md src="doc/doc.md"></zero-md>
+
+</body>
+</html>