refactor(): remove docs folder and update readme file

Author: José Postiga

README.md

@@ -1,4 +1,4 @@
-## Laravel-Portugal API
+# Laravel-Portugal API
 
 ![Run tests](https://github.com/laravel-portugal/api/workflows/Run%20tests/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/laravel-portugal/api/badge.svg?branch=master)](https://coveralls.io/github/laravel-portugal/api?branch=master)
@@ -10,29 +10,47 @@
 - PHP >= 7.4
 - MySQL >= 8, MariaDB >= 10 or PostgreSQL >= 11
 
-**Steps to activate this project**
+**Activation**
 
 1. Clone this repository.
 2. Run `composer install` to install all dependencies (add `--no-dev` if you're using this in production).
 3. Run `cp .env.example .env` to create an `.env` file based on the distributed `.env.example` file.
 4. Update the `.env` file with a new `APP_KEY` and the connection details for the database.
 5. Run `php artisan migrate` to create the database schema.
 
-## Testing
+**Deployment**
 
-This project is fully tested. We have an [automatic pipeline](https://github.com/laravel-portugal/api/actions) and an [automatic code quality analysis](https://coveralls.io/github/laravel-portugal/api) tool set up to continuously test and assert the quality of all code published in this repository, but you can execute the test suite yourself by running the following command:
+This project is prepared to be run with Docker. There are docker-compose files that try to provide an easy way to deploy this project to your infrastructure. You should create a `docker-compose.override.yml` (probably based on the example file provided), and change it to your specific needs.
 
-``` bash
-vendor/bin/phpunit
-```
+## Documentation
 
-_Note: This assumes you've run `composer install` (without the `--no-dev` option)._
+This service API is organized around REST and has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
 
-**We aim to keep the master branch always deployable.** Exceptions may happen, but they should be extremely rare.
+### Authentication
 
-## Documentation
+Authentication to the API is performed via checking for the presence of a Bearer token on the Authorization header of a request. This token is an encoded JWT that's generated by exchanging the username and the password, of a previously registered user account, on the `/login` endpoint.
+
+### Include relationship data
+
+Many objects allow you to request additional relationship information as an expanded response, by using the `include` request parameter. This parameter is available on all API requests that have related data available to be included and applies to the response of that request only. You can, however, include multiple objects at once by identifying multiple items in the `include` query parameter separated by a comma.
+
+### Errors
+
+This API uses conventional HTTP response codes to indicate the success or failure of a request. Codes in the `2xx` range indicate success, codes in the `4xx` range indicate a validation error (e.g., a required parameter was omitted) and codes in the `5xx` range indicate an error with the service internal programming (these should be very rare). Check the table below for a list of possible status codes and their meaning:
+
+Code | Status               | Description
+---- | ------               | -----------
+200  | OK                   | Everything worked as expected.
+401  | Unauthorized         | No valid authorization header value provided.
+403	 | Forbidden            | The supplied authorization key doesn't have permission to perform the request.
+404  | Not Found            | The requested resource doesn't exist.
+422  | Unprocessable Entity | The request was unacceptable, often due to missing a required parameter.
+429  | Too Many Requests    | Too many requests hit the API too quickly.
+5xx  | Server Errors        | Something went wrong on the internal service programming.
 
-Please see the [public documentation site](https://laravel-portugal.stoplight.io/docs/api/docs/1.Introduction.md).
+## Support
+
+If you have any problems and need assistance, feel free to use the issue tracker to ask for support. However, be patient! Your request might take time to be answered.
 
 ## Changelog
 
@@ -42,6 +60,18 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
 
 Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
+## Testing
+
+This project is fully tested. We have an [automatic pipeline](https://github.com/laravel-portugal/api/actions) and an [automatic code quality analysis](https://coveralls.io/github/laravel-portugal/api) tool set up to continuously test and assert the quality of all code published in this repository, but you can execute the test suite yourself by running the following command:
+
+``` bash
+vendor/bin/phpunit
+```
+
+_Note: This assumes you've run `composer install` (without the `--no-dev` option)._
+
+**We aim to keep the master branch always deployable.** Exceptions may happen, but they should be extremely rare.
+
 ## Security
 
 Please see [SECURITY](SECURITY.md) for details.