From bed9353a23750d42c261493b44b3337f3c5d1170 Mon Sep 17 00:00:00 2001
From: Andrea Vassallo <andrea.vassallo.94@gmail.com>
Date: Tue, 10 Jan 2023 14:51:37 +0100
Subject: [PATCH] Add a better description for the api key

Some endpoints that are not related to the users can be used without
the api key changing the Solidus configuration.
Add the instruction to do it.
---
 api/openapi/authentication.md   | 2 ++
 api/openapi/solidus-api.oas.yml | 7 ++++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/api/openapi/authentication.md b/api/openapi/authentication.md
index 4ae9674a279..025aed18c56 100644
--- a/api/openapi/authentication.md
+++ b/api/openapi/authentication.md
@@ -20,6 +20,8 @@ curl --header "Authorization: Bearer 1a6a9936ad150a2ee345c65331da7a3ccc2de" http
 
 By default, API keys are only generated for admins, but you can easily customize Solidus to generate them for all users, which is useful for instance if you want users to be able to sign in and manage their profile via the API.
 
+The `API key` is mandatory for each endpoint by default. You can change this configuration [here](https://github.com/solidusio/solidus/blob/master/api/lib/spree/api_configuration.rb#L5) if you want to avoid the default behaviour exposing some endpoints without an API key. An example is the [GET product list](https://solidus.stoplight.io/docs/solidus/08307f3d809e7-list-products).
+
 ### Order token
 
 For allowing guests to manage their cart and place their order, you can use the order's guest token. This token is contained in the `guest_token` property of the order, and it allows you to perform certain checkout-related operations on the order such as managing line items, completing the checkout flow etc.
diff --git a/api/openapi/solidus-api.oas.yml b/api/openapi/solidus-api.oas.yml
index b9631b91683..5e8f90f93c5 100644
--- a/api/openapi/solidus-api.oas.yml
+++ b/api/openapi/solidus-api.oas.yml
@@ -1,4 +1,7 @@
 openapi: 3.0.3
+x-stoplight:
+  docs:
+    showModels: false
 info:
   title: Solidus API
   version: '1.0'
@@ -8,9 +11,6 @@ info:
     url: 'https://solidus.io'
   license:
     name: ''
-x-stoplight:
-  docs:
-    showModels: false
 paths:
   /products:
     get:
@@ -5928,6 +5928,7 @@ components:
       type: apiKey
       name: Authorization
       in: header
+      description: 'The `API key` is mandatory for each endpoint by default. You can change this configuration [here](https://github.com/solidusio/solidus/blob/master/api/lib/spree/api_configuration.rb#L5) if you want to avoid the default behaviour exposing some endpoints without an API key. An example is the [GET product list](https://solidus.stoplight.io/docs/solidus/08307f3d809e7-list-products).'
     order-token:
       type: apiKey
       name: X-Spree-Order-Token