Improve API documentation: fix for demo server path, added 403 error responses, improved schema for paginated responses (#303)

Author: romalytvynenko

src/CachetCoreServiceProvider.php

@@ -231,7 +231,7 @@ private function configureScramble(): void
             ->withDocumentTransformers(function (OpenApi $openApi) {
                 $openApi->info->description = 'API documentation for Cachet, the open-source, self-hosted status page system.';
 
-                $openApi->addServer(Server::make('https://v3.cachethq.io')->setDescription('The Cachet v3 demo server.'));
+                $openApi->addServer(Server::make('https://v3.cachethq.io/api')->setDescription('The Cachet v3 demo server.'));
                 $openApi->secure(SecurityScheme::http('bearer'));
             })
             ->withOperationTransformers(function (Operation $operation, RouteInfo $routeInfo) {

src/Concerns/GuardsApiAbilities.php

@@ -9,6 +9,7 @@
 
 trait GuardsApiAbilities
 {
+    /** @throws MissingAbilityException */
     public function guard(string $ability): void
     {
         /** @var User $user */