improve OpenAPI schema so it is better rendered on Stoplight

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/GehirnInc/crypt v0.0.0-20200316065508-bb7000b8a962
 	github.com/StackExchange/wmi v0.0.0-20210224194228-fe8f1750fd46 // indirect
 	github.com/alexedwards/argon2id v0.0.0-20201228115903-cf543ebc1f7b
-	github.com/aws/aws-sdk-go v1.37.24
+	github.com/aws/aws-sdk-go v1.37.25
 	github.com/coreos/go-systemd v0.0.0-20191104093116-d3cd4ed1dbcf // indirect
 	github.com/eikenb/pipeat v0.0.0-20200430215831-470df5986b6d
 	github.com/fclairamb/ftpserverlib v0.13.0
@@ -40,7 +40,7 @@ require (
 	github.com/otiai10/copy v1.5.0
 	github.com/pelletier/go-toml v1.8.1 // indirect
 	github.com/pires/go-proxyproto v0.5.0
-	github.com/pkg/sftp v1.12.1-0.20210306114423-5b7da38a9cdb
+	github.com/pkg/sftp v1.13.0
 	github.com/prometheus/client_golang v1.9.0
 	github.com/prometheus/common v0.18.0 // indirect
 	github.com/prometheus/procfs v0.6.0 // indirect
@@ -65,7 +65,7 @@ require (
 	golang.org/x/crypto v0.0.0-20210220033148-5ea612d1eb83
 	golang.org/x/net v0.0.0-20210226172049-e18ecbb05110
 	golang.org/x/oauth2 v0.0.0-20210220000619-9bb904979d93 // indirect
-	golang.org/x/sys v0.0.0-20210305034016-7844c3c200c3
+	golang.org/x/sys v0.0.0-20210305230114-8fe3ee5dd75b
 	golang.org/x/time v0.0.0-20210220033141-f8bda1e9f3ba // indirect
 	google.golang.org/api v0.40.0
 	google.golang.org/genproto v0.0.0-20210303154014-9728d6b83eeb // indirect

go.sum

@@ -116,8 +116,8 @@ github.com/aws/aws-sdk-go v1.15.27/go.mod h1:mFuSZ37Z9YOHbQEwBWztmVzqXrEkub65tZo
 github.com/aws/aws-sdk-go v1.23.20/go.mod h1:KmX6BPdI08NWTb3/sm4ZGu5ShLoqVDhKgpiN924inxo=
 github.com/aws/aws-sdk-go v1.27.0/go.mod h1:KmX6BPdI08NWTb3/sm4ZGu5ShLoqVDhKgpiN924inxo=
 github.com/aws/aws-sdk-go v1.36.1/go.mod h1:hcU610XS61/+aQV88ixoOzUoG7v3b31pl2zKMmprdro=
-github.com/aws/aws-sdk-go v1.37.24 h1:UmdPwGITvz//eFxNyuPlkq8KLlu4ZGvowsCQs+uFIp4=
+github.com/aws/aws-sdk-go v1.37.25 h1:q1C/ILIVusSmqgWG4tFU0uVt3Zm+1I3L2BmNCd2Ug4Q=
-github.com/aws/aws-sdk-go v1.37.24/go.mod h1:hcU610XS61/+aQV88ixoOzUoG7v3b31pl2zKMmprdro=
+github.com/aws/aws-sdk-go v1.37.25/go.mod h1:hcU610XS61/+aQV88ixoOzUoG7v3b31pl2zKMmprdro=
 github.com/aws/aws-sdk-go-v2 v0.18.0/go.mod h1:JWVYvqSMppoMJC0x5wdwiImzgXTI9FuZwxzkQq9wy+g=
 github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973/go.mod h1:Dwedo/Wpr24TaqPxmxbtue+5NUziq4I4S80YR8gNf3Q=
 github.com/beorn7/perks v1.0.0/go.mod h1:KWe93zE9D1o94FZ5RNwFwVgaQK1VOXiVxmqh+CedLV8=
@@ -573,8 +573,8 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/profile v1.2.1/go.mod h1:hJw3o1OdXxsrSjjVksARp5W95eeEaEfptyVZyv6JUPA=
 github.com/pkg/sftp v1.10.1/go.mod h1:lYOWFsE0bwd1+KfKJaKeuokY15vzFx25BLbzYYoAxZI=
-github.com/pkg/sftp v1.12.1-0.20210306114423-5b7da38a9cdb h1:kMNGy8CB8a49gKT+Sb7+ReG15NzJBKviZ8Zds9f0aHM=
+github.com/pkg/sftp v1.13.0 h1:Riw6pgOKK41foc1I1Uu03CjvbLZDXeGpInycM4shXoI=
-github.com/pkg/sftp v1.12.1-0.20210306114423-5b7da38a9cdb/go.mod h1:41g+FIPlQUTDCveupEmEA65IoiQFrtgCeDopC4ajGIM=
+github.com/pkg/sftp v1.13.0/go.mod h1:41g+FIPlQUTDCveupEmEA65IoiQFrtgCeDopC4ajGIM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/posener/complete v1.1.1/go.mod h1:em0nMJCgc9GFtwrmVmEMR/ZL6WyhyjMBndrE9hABlRI=
@@ -843,8 +843,8 @@ golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210217105451-b926d437f341/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210220050731-9a76102bfb43/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210225134936-a50acf3fe073/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210305034016-7844c3c200c3 h1:RdE7htvBru4I4VZQofQjCZk5W9+aLNlSF5n0zgVwm8s=
+golang.org/x/sys v0.0.0-20210305230114-8fe3ee5dd75b h1:ggRgirZABFolTmi3sn6Ivd9SipZwLedQ5wR0aAKnFxU=
-golang.org/x/sys v0.0.0-20210305034016-7844c3c200c3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210305230114-8fe3ee5dd75b/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1 h1:v+OssWQX+hTHEmOBgwxdZxK4zHq3yOs8F9J7mk0PY8E=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=

httpd/schema/openapi.yaml

@@ -31,7 +31,7 @@ paths:
       tags:
         - healthcheck
       summary: health check
-      description: Health endpoint to check if the application is running and responding to requests
+      description: This endpoint can be used to check if the application is running and responding to requests
       operationId: healthz
       responses:
         '200':
@@ -47,7 +47,7 @@ paths:
         - BasicAuth: []
       tags:
         - token
-      summary: Get an access token
+      summary: Get a new access token
       description: Returns an access token and its expiration
       operationId: get_token
       responses:
@@ -69,7 +69,7 @@ paths:
     get:
       tags:
         - token
-      summary: Logout
+      summary: Invalidate
       description: Allows to invalidate a token before its expiration
       operationId: logout
       responses:
@@ -92,7 +92,7 @@ paths:
       tags:
         - maintenance
       summary: Get version details
-      description: 'Returns version details such as the version number, build date commit hash and enabled features'
+      description: 'Returns version details such as the version number, build date, commit hash and enabled features'
       operationId: get_version
       responses:
         '200':
@@ -114,7 +114,7 @@ paths:
       tags:
         - admins
       summary: Change admin password
-      description: Change the password for the logged in admin
+      description: Changes the password for the logged in admin
       operationId: change_admin_password
       requestBody:
         required: true
@@ -142,7 +142,7 @@ paths:
       tags:
         - connections
       summary: Get connections details
-      description: Get the active users and info about their uploads/downloads
+      description: Returns the active users and info about their current uploads/downloads
       operationId: get_connections
       responses:
         '200':
@@ -166,7 +166,7 @@ paths:
       tags:
         - connections
       summary: Close connection
-      description: Terminate an active connection
+      description: Terminates an active connection
       operationId: close_connection
       parameters:
         - name: connectionID
@@ -229,8 +229,8 @@ paths:
     post:
       tags:
         - defender
-      description: Unban
+      summary: Unban
-      summary: Removes the specified IPv4/IPv6 from the banned ones
+      description: Removes the specified IPv4/IPv6 from the banned ones
       operationId: unban_host
       requestBody:
         required: true
@@ -297,7 +297,7 @@ paths:
       tags:
         - quota
       summary: Get quota scans
-      description: Get the active quota scans for users home directories
+      description: Returns active user quota scans
       operationId: get_quota_scans
       responses:
         '200':
@@ -319,8 +319,8 @@ paths:
     post:
       tags:
         - quota
-      summary: start a new user quota scan
+      summary: Start user quota scan
-      description: A quota scan update the number of files and their total size for the specified user
+      description: Starts a new quota scan for the given user. A quota scan update the number of files and their total size for the specified user
       operationId: start_quota_scan
       requestBody:
         required: true
@@ -356,7 +356,7 @@ paths:
       tags:
         - quota
       summary: Update user quota limits
-      description: Set the current used quota limits for the given user
+      description: Sets the current used quota limits for the given user
       operationId: quota_update
       parameters:
         - in: query
@@ -407,8 +407,8 @@ paths:
     put:
       tags:
         - quota
-      summary: update the folder used quota limits
+      summary: Update folder quota limits
-      description: Set the current used quota limits for the given folder
+      description: Sets the current used quota limits for the given folder
       operationId: folder_quota_update
       parameters:
         - in: query
@@ -460,7 +460,7 @@ paths:
       tags:
         - quota
       summary: Get folders quota scans
-      description: Get active quota scans for folders
+      description: Returns the active quota scans for folders
       operationId: get_folders_quota_scans
       responses:
         '200':
@@ -482,8 +482,8 @@ paths:
     post:
       tags:
         - quota
-      summary: start a new folder quota scan
+      summary: Start folder quota scan
-      description: A quota scan update the number of files and their total size for the specified folder
+      description: Starts a new quota scan for the given user. A quota scan update the number of files and their total size for the specified folder
       operationId: start_folder_quota_scan
       requestBody:
         required: true
@@ -570,9 +570,9 @@ paths:
     post:
       tags:
         - folders
-      summary: Adds a new folder
+      summary: Add folder
       operationId: add_folder
-      description: a new folder with the specified mapped_path will be added. To update the used quota parameters a quota scan is needed
+      description: Adds a new folder. A quota scan is required to update the used files/size
       requestBody:
         required: true
         content:
@@ -607,8 +607,8 @@ paths:
     get:
       tags:
         - folders
-      summary: Find user by name
+      summary: Find folders by name
-      description: For security reasons the hashed password is omitted in the response
+      description: Returns the folder with the given name if it exists.
       operationId: get_folder_by_name
       responses:
         '200':
@@ -633,7 +633,7 @@ paths:
       tags:
         - folders
       summary: Update folder
-      description: Update an existing user
+      description: Updates an existing folder
       operationId: update_folder
       requestBody:
         required: true
@@ -666,7 +666,7 @@ paths:
       tags:
         - folders
       summary: Delete folder
-      description: Delete an existing folder
+      description: Deletes an existing folder
       operationId: delete_folder
       responses:
         '200':
@@ -693,8 +693,8 @@ paths:
     get:
       tags:
         - admins
-      summary: Returns an array with one or more admins
+      summary: Get admins
-      description: For security reasons hashed passwords are omitted in the response
+      description: Returns an array with one or more admins. For security reasons hashed passwords are omitted in the response
       operationId: get_admins
       parameters:
         - in: query
@@ -746,7 +746,7 @@ paths:
       tags:
         - admins
       summary: Add admin
-      description: Add a new admin
+      description: Adds a new admin
       operationId: add_admin
       requestBody:
         required: true
@@ -798,8 +798,8 @@ paths:
     get:
       tags:
         - admins
-      summary: Find admin by username
+      summary: Find admins by username
-      description: For security reasons the hashed password is omitted in the response
+      description: Returns the admin with the given username, if it exists. For security reasons the hashed password is omitted in the response
       operationId: get_admin_by_username
       responses:
         '200':
@@ -824,7 +824,7 @@ paths:
       tags:
         - admins
       summary: Update admin
-      description: Update an existing admin
+      description: Updates an existing admin
       operationId: update_admin
       requestBody:
         required: true
@@ -857,7 +857,7 @@ paths:
       tags:
         - admins
       summary: Delete admin
-      description: Delete an existing admin
+      description: Deletes an existing admin
       operationId: delete_admin
       responses:
         '200':
@@ -884,8 +884,8 @@ paths:
     get:
       tags:
         - users
-      summary: Returns an array with one or more users
+      summary: Get users
-      description: For security reasons hashed passwords are omitted in the response
+      description: Returns an array with one or more users. For security reasons hashed passwords are omitted in the response
       operationId: get_users
       parameters:
         - in: query
@@ -937,7 +937,7 @@ paths:
       tags:
         - users
       summary: Add user
-      description: Add a new user
+      description: Adds a new user
       operationId: add_user
       requestBody:
         required: true
@@ -973,8 +973,8 @@ paths:
     get:
       tags:
         - users
-      summary: Find user by username
+      summary: Find users by username
-      description: For security reasons the hashed password is omitted in the response
+      description: Returns the user with the given username if it exists. For security reasons the hashed password is omitted in the response
       operationId: get_user_by_username
       responses:
         '200':
@@ -999,7 +999,7 @@ paths:
       tags:
         - users
       summary: Update user
-      description: 'Update an existing user and optionally disconnect, if connected, to apply the new settings'
+      description: 'Updates an existing user and optionally disconnects it, if connected, to apply the new settings'
       operationId: update_user
       parameters:
         - in: query
@@ -1044,7 +1044,7 @@ paths:
       tags:
         - users
       summary: Delete user
-      description: Delete an existing user
+      description: Deletes an existing user
       operationId: delete_user
       responses:
         '200':
@@ -1072,7 +1072,7 @@ paths:
       tags:
         - maintenance
       summary: Get status
-      description: Retrieve the status of the active services
+      description: Retrieves the status of the active services
       operationId: get_status
       responses:
         '200':
@@ -1095,8 +1095,8 @@ paths:
     get:
       tags:
         - maintenance
-      summary: Backup SFTPGo data as data provider independent JSON
+      summary: Dump data
-      description: 'The backup can be saved in a local file on the server, to avoid exposing sensitive data over the network, or returned as response body. The output of dumpdata can be used as input for loaddata'
+      description: 'Backups data as data provider independent JSON. The backup can be saved in a local file on the server, to avoid exposing sensitive data over the network, or returned as response body. The output of dumpdata can be used as input for loaddata'
       operationId: dumpdata
       parameters:
         - in: query
@@ -1177,8 +1177,8 @@ paths:
     get:
       tags:
         - maintenance
-      summary: Restore SFTPGo data from a JSON backup file on the server
+      summary: Load data from path
-      description: 'Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
+      description: 'Restores SFTPGo data from a JSON backup file on the server. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
       operationId: loaddata_from_file
       parameters:
         - in: query
@@ -1209,8 +1209,8 @@ paths:
     post:
       tags:
         - maintenance
-      summary: Restore SFTPGo data from a JSON backup
+      summary: Load data
-      description: 'Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
+      description: 'Restores SFTPGo data from a JSON backup. Users, folders and admins will be restored one by one and the restore is stopped if a user/folder/admin cannot be added or updated, so it could happen a partial restore'
       operationId: loaddata_from_request_body
       requestBody:
         required: true