From 91fb2985106fadcd70338e8b752dbd17ff703f1e Mon Sep 17 00:00:00 2001
From: Blake Erickson <o.blakeerickson@gmail.com>
Date: Thu, 4 Feb 2021 18:43:40 -0700
Subject: [PATCH] DEV: Add description and logo to api docs (#11984)

* DEV: Add description and logo to api docs

* Rename method to avoid name collision
---
 spec/swagger_helper.rb | 67 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb
index 262c28f86cf..4f577fd697f 100644
--- a/spec/swagger_helper.rb
+++ b/spec/swagger_helper.rb
@@ -13,6 +13,67 @@ def load_spec_schema(name)
   SpecSchemas::SpecLoader.new(name).load
 end
 
+def api_docs_description
+  <<~HEREDOC
+    This page contains the documentation on how to use Discourse through API calls.
+
+    > Note: For any endpoints not listed you can follow the
+    [reverse engineer the Discourse API](https://meta.discourse.org/t/-/20576)
+    guide to figure out how to use an API endpoint.
+
+    ### Request Content-Type
+
+    The Content-Type for POST and PUT requests can be set to `application/x-www-form-urlencoded`,
+    `multipart/form-data`, or `application/json`.
+
+    ### Endpoint Names and Response Content-Type
+
+    Most API endpoints provide the same content as their HTML counterparts. For example
+    the URL `/categories` serves a list of categories, the `/categories.json` API provides the
+    same information in JSON format.
+
+    Instead of sending API requests to `/categories.json` you may also send them to `/categories`
+    and add an `Accept: application/json` header to the request to get the JSON response.
+    Sending requests with the `Accept` header is necessary if you want to use URLs
+    for related endpoints returned by the API, such as pagination URLs.
+    These URLs are returned without the `.json` prefix so you need to add the header in
+    order to get the correct response format.
+
+    ### Authentication
+
+    Some endpoints do not require any authentication, pretty much anything else will
+    require you to be authenticated.
+
+    To become authenticated you will need to create an API Key from the admin panel.
+
+    Once you have your API Key you can pass it in along with your API Username
+    as an HTTP header like this:
+
+    ```
+    curl -X GET "http://127.0.0.1:3000/admin/users/list/active.json" \
+    -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
+    -H "Api-Username: system"
+    ```
+
+    and this is how POST requests will look:
+
+    ```
+    curl -X POST "http://127.0.0.1:3000/categories" \
+    -H "Content-Type: multipart/form-data;" \
+    -H "Api-Key: 714552c6148e1617aeab526d0606184b94a80ec048fc09894ff1a72b740c5f19" \
+    -H "Api-Username: system" \
+    -F "name=89853c20-4409-e91a-a8ea-f6cdff96aaaa" \
+    -F "color=49d9e9" \
+    -F "text_color=f0fcfd"
+    ```
+
+    ### Boolean values
+
+    If an endpoint accepts a boolean be sure to specify it as a lowercase
+    `true` or `false` value unless noted otherwise.
+  HEREDOC
+end
+
 RSpec.configure do |config|
   # Specify a root folder where Swagger JSON files are generated
   # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
@@ -30,7 +91,11 @@ RSpec.configure do |config|
       openapi: '3.0.3',
       info: {
         title: 'Discourse API Documentation',
-        version: 'latest'
+        'x-logo': {
+          url: 'https://discourse-meta.s3-us-west-1.amazonaws.com/optimized/3X/9/d/9d543e92b15b06924249654667a81441a55867eb_1_690x184.png',
+        },
+        version: 'latest',
+        description: api_docs_description
       },
       paths: {},
       servers: [