Update documentation

Author: man90es

README.md

@@ -8,48 +8,14 @@ A scraper for Black Desert Online player in-game data with a REST API. It curren
 - [Ikusa](https://ikusa.site) ([Source](https://github.com/sch-28/ikusa_api)): a powerful tool that allows you to analyze your game logs and gain valuable insights into your combat performance.
 
 ## How to start using it
-There are two ways to use this API in your apps:
-* https://bdo.hemlo.cc/communityapi/v1 is the "official" instance hosted by me. Using it is easy but it may be slow or even become unresponsive. The API documentation can be viewed [here](https://gitlab.com/man90/black-desert-social-rest-api/-/tree/master/doc/api/openapi.json).
-* If you want to have more control over the API, host the scraper yourself. The repository is preconfigured to be deployable on Heroku, can be easily deployed with Docker or built manually for a VPS/VDS. To do this, follow these steps:
-	1. Build the server from the source code following [this guide](doc/buildingFromSource.md).
-	2. (Optional) Set the environment variables. The list of available variables is in the section below.
-	3. Run the binary. Possible flags are described in a section below.
-	4. Use the API as described in the [documentation](https://gitlab.com/man90/black-desert-social-rest-api/-/tree/master/doc/api/openapi.json).
+There are two ways to use this scraper for your needs:
+* By querying https://bdo.hemlo.cc/communityapi/v1 — this is the "official" instance hosted by me.
+* If you want to have more control over the API, host the scraper yourself. It's [available on DockerHub](https://hub.docker.com/repository/docker/man90/bdo-rest-api) (exposes port 8001), preconfigured for Heroku, and can be built from source as described in [this guide](docs/buildingFromSource.md) (this gives you a bit more control over how the scraper behaves).
 
-## Environment variables
-Catch requests on a specific port (8001 by default):
-```bash
-export PORT=3000
-```
-
-Use a proxy to make requests to BDO servers (direct by default):
-```bash
-export PROXY=http://123.123.123.123:8080
-# or
-export PROXY="http://123.123.123.123:8080 http://124.124.124.124:8081"
-```
-
-## Flags
-These flags override environment variables.
-```
--cachecap int
-	Cache capacity (default 10000)
--cachettl int
-	Cache TTL in minutes (default 180)
--port int
-	Port to catch requests on (default 8001)
--proxy string
-	Open proxy address to make requests to BDO servers
--verbose
-	Print out additional logs into stdout
-```
-Use them like this:
-```bash
-./bdo-rest-api -proxy="http://192.168.0.0.1:8080" -cachettl=30
-```
+API documentation can be viewed [here](https://octoman90.github.io/BDO-REST-API/).
 
 ## Known bugs
-There is a number of bugs that the official BDO website has. This collector does not do anything about them for the sake of simplicity, so your apps may need to use the [workarounds](doc/brokenStuff.md).
+There is a number of bugs that the official BDO website has. This scraper does not do anything about them for the sake of simplicity, so your apps may need to use [workarounds](docs/brokenStuff.md).
 
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

doc/buildingFromSource.md

@@ -0,0 +1,50 @@
+# Building from source
+Building the scraper from source may be preferable in some cases. This way, the app has a smaller footprint and gives you more control than a [Docker image](https://hub.docker.com/repository/docker/man90/bdo-rest-api).
+
+## Prerequisites:
+- GNU/Linux (other platforms should work as well but I haven't tested them)
+- Go compiler >=v1.15
+
+## Compilation
+By default, scraped results are cached in memory and stored for up to 2 hours. This helps to ease the pressure on BDO servers and decreases the response time tremendously (for cached responses). Use this command to compile the app:
+```bash
+go build
+```
+
+If you don't want to cache scraped results (e.g., if you are 100% sure that there will be no similar requests sent to the API), you can also use this command instead:
+```bash
+go build -tags "cacheless"
+```
+
+## Environment variables
+Catch requests on a specific port (8001 by default):
+```bash
+export PORT=3000
+```
+
+Use a proxy to make requests to BDO servers (direct by default):
+```bash
+export PROXY=http://123.123.123.123:8080
+# or
+export PROXY="http://123.123.123.123:8080 http://124.124.124.124:8081"
+```
+
+## Flags
+These flags override environment variables.
+```
+-cachecap int
+	Cache capacity (default 10000)
+-cachettl int
+	Cache TTL in minutes (default 180)
+-port int
+	Port to catch requests on (default 8001)
+-proxy string
+	Open proxy address to make requests to BDO servers
+-verbose
+	Print out additional logs into stdout
+```
+
+Use them like this:
+```bash
+./bdo-rest-api -proxy="http://192.168.0.0.1:8080" -cachettl=30
+```

doc/brokenStuff.md renamed to docs/brokenStuff.md

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+
+<title>BDO-REST-API documentation</title>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+<style>
+	body {
+		margin: 0;
+		padding: 0;
+	}
+</style>
+
+<redoc spec-url="https://raw.githubusercontent.com/octoman90/BDO-REST-API/master/docs/openapi.json"></redoc>
+<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>

docs/buildingFromSource.md

@@ -6,10 +6,10 @@
 	},
 	"servers": [
 		{
-			"url": "https://bdo.hemlo.cc/communityapi/v1"
+			"url": "https://bdo.hemlo.cc/communityapi"
 		},
 		{
-			"url": "http://localhost:8001/v1"
+			"url": "http://localhost:8001"
 		}
 	],
 	"components": {
@@ -21,7 +21,7 @@
 				"schema": {
 					"type": "string",
 					"enum": ["EU", "NA", "SA"],
-					"example": "EU"
+					"default": "EU"
 				}
 			}
 		},
@@ -33,15 +33,15 @@
 				"description": "Not Found: try requesting something else."
 			},
 			"503": {
-				"description": "Service Unavailable: [https://naeu.playblackdesert.com](naeu.playblackdesert.com) is currently under maintenance and the data requested is not cached."
+				"description": "Service Unavailable: [https://naeu.playblackdesert.com](naeu.playblackdesert.com) is currently under maintenance and requested data is not cached."
 			}
 		}
 	},
 	"paths": {
-		"/adventurer": {
+		"/v1/adventurer": {
 			"get": {
 				"summary": "Retrieve player's profile.",
-				"description": "Retrieve the full profile of a single player by his or her profileTarget.",
+				"description": "Retrieve the full profile of a single player by his or her profileTarget. Watch out for the \"privacy\" attribute that is added to the response when the player whose profile is requested turned on at least one of the privacy options BDO website has. It is a single number that you can decode using bitmasks. `0b0001` for private character levels, `0b0010` for private guild, `0b0100` for private contribution points and `0b1000` for private lifeskill levels. If the attribute is equal to `0b1111` then everything is set to private.",
 				"operationId": "getAdventurer",
 				"parameters": [
 					{
@@ -60,13 +60,13 @@
 						"schema": {
 							"type": "string",
 							"enum": ["EU", "NA", "SA"],
-							"example": "EU"
+							"default": "EU"
 						}
 					}
 				],
 				"responses": {
 					"200": {
-						"description": "Watch out for the \"privacy\" attribute that is added to the response when the player whose profile is requested turned on at least one of the privacy options BDO website has. It is a single number that you can decode using bitmasks. `0b0001` for private character levels, `0b0010` for private guild, `0b0100` for private contribution points and `0b1000` for private lifeskill levels. If the attribute is equal to `0b1111` then everything is set to private.",
+						"description": "OK.",
 						"content": {
 							"application/json": {
 								"schema": {
@@ -190,7 +190,7 @@
 				}
 			}
 		},
-		"/adventurer/search": {
+		"/v1/adventurer/search": {
 			"get": {
 				"summary": "Search for a player.",
 				"description": "Search for a player by a combination of his or her region and family/character name.",
@@ -249,7 +249,7 @@
 											},
 											"region": {
 												"type": "string",
-												"enum": ["EU", "NA"]
+												"enum": ["EU", "NA", "SA"]
 											},
 											"guild": {
 												"properties": {
@@ -301,7 +301,7 @@
 				}
 			}
 		},
-		"/guild": {
+		"/v1/guild": {
 			"get": {
 				"summary": "Retrieve guild profile.",
 				"description": "Retrieve the profile of a guild by its name.",
@@ -335,7 +335,7 @@
 										},
 										"region": {
 											"type": "string",
-											"enum": ["EU", "NA"]
+											"enum": ["EU", "NA", "SA"]
 										},
 										"createdOn": {
 											"type": "string",
@@ -395,7 +395,7 @@
 				}
 			}
 		},
-		"/guild/search": {
+		"/v1/guild/search": {
 			"get": {
 				"summary": "Search for a guild.",
 				"description": "Search for a guild by combination of its region and name.",
@@ -440,7 +440,7 @@
 											},
 											"region": {
 												"type": "string",
-												"enum": ["EU", "NA"]
+												"enum": ["EU", "NA", "SA"]
 											},
 											"createdOn": {
 												"type": "string",