Adding introduction, Authentication and Usage examples sections to th…

…e API docs. (#5858)

BTCPayServer/wwwroot/swagger/v1/swagger.template.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "BTCPay Greenfield API",
     "version": "v1",
-    "description": "A full API to use your BTCPay Server",
+    "description": "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https:\/\/docs.btcpayserver.org\/API\/Greenfield\/v1\/#tag\/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https:\/\/docs.btcpayserver.org\/BTCPayServer\/greenfield-authorization\/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https:\/\/mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application\/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE\/api\/v1\/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application\/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE\/api\/v1\/stores\/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https:\/\/docs.btcpayserver.org\/Development\/GreenFieldExample\/)\n- [Javascript\/Node.Js](https:\/\/docs.btcpayserver.org\/Development\/GreenFieldExample-NodeJS\/)\n- [PHP](https:\/\/docs.btcpayserver.org\/Development\/GreenFieldExample-PHP\/)\n\n",
     "contact": {
       "name": "BTCPay Server",
       "url": "https://btcpayserver.org"