Auto Generate API docs with Scribe

.env.doc

@@ -0,0 +1,4 @@
+APP_ENV=local
+APP_KEY=base64:x1DbRe+bvcFalJVHx3pturXHXXvVqx3fBTeS4Nc3re8=
+APP_URL=https://app.getinput.co
+

.gitignore

@@ -2,6 +2,8 @@
 /node_modules
 /public/hot
 /public/build
+/public/docs
+/public/vendor/scribe
 /public/storage
 /public/js
 /public/css
@@ -19,5 +21,6 @@ npm-debug.log
 yarn-error.log
 /.idea
 /.vscode
+/.scribe
 coverage
 _ide_helper.php

Dockerfile

@@ -73,13 +73,17 @@ COPY --from=asset_builder /var/www/html/public/js ./public/js
 RUN touch /var/www/html/storage/database.sqlite
 RUN php artisan migrate --force
 
-RUN php artisan route:cache
-RUN php artisan view:cache
 RUN php artisan storage:link
 
 RUN echo "APP_KEY=" > .env
 RUN php artisan key:generate
 
+# Generate the API Documentation
+RUN php artisan scribe:generate --env doc
+
+RUN php artisan route:cache
+RUN php artisan view:cache
+
 USER root
 COPY --chown=nobody:nobody ./start-container.sh /opt/input/start-container.sh
 RUN chmod +x /opt/input/start-container.sh

app/Http/Controllers/Api/CreateFormSessionController.php

@@ -7,9 +7,16 @@
 use App\Models\FormSession;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
+use Knuckles\Scribe\Attributes\Group;
 
 class CreateFormSessionController extends Controller
 {
+    /**
+     * Create a new form session
+     *
+     * This endpoint creates a new form session and returns the session token. This token is required to submit the form. Using the same token on multiple submissions will result in the old submission being overwritten.
+     */
+    #[Group('Public Form Endpoints')]
     public function __invoke(Request $request, Form $form)
     {
         $session = FormSession::create([

app/Http/Controllers/Api/DeleteFormSubmissionController.php

@@ -5,9 +5,16 @@
 use App\Http\Controllers\Controller;
 use App\Models\Form;
 use App\Models\FormSession;
+use Knuckles\Scribe\Attributes\Group;
 
 class DeleteFormSubmissionController extends Controller
 {
+    /**
+     * Delete a single form submission
+     *
+     * This endpoint deletes a single form submission.
+     */
+    #[Group('Form Submissions')]
     public function __invoke(Form $form, FormSession $session)
     {
         $this->authorize('update', $form);

app/Http/Controllers/Api/DuplicateFormController.php

@@ -5,9 +5,20 @@
 use App\Http\Controllers\Controller;
 use App\Models\Form;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\BodyParam;
+use Knuckles\Scribe\Attributes\Group;
 
 class DuplicateFormController extends Controller
 {
+    /**
+     * Duplicates a form
+     *
+     * This endpoint duplicates a form for the authenticated user.
+     */
+    #[Group('Forms')]
+    #[Authenticated]
+    #[BodyParam('name', 'string', 'The name of the new form.', false, example: 'Copy of My Form')]
     public function __invoke(Request $request, Form $form)
     {
         $this->authorize('update', $form);

app/Http/Controllers/Api/FormBlockController.php

@@ -9,9 +9,18 @@
 use App\Models\Form;
 use App\Models\FormBlock;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
+#[Group('Form Blocks')]
+#[Authenticated]
 class FormBlockController extends Controller
 {
+    /**
+     * Get all form blocks
+     *
+     * This endpoint returns all form blocks of a form. A form block is like a single page on the form. Each block has a type that can contain different block interactions based on that type.
+     */
     public function index(Request $request, Form $form)
     {
         $this->authorize('view', $form);
@@ -28,6 +37,11 @@ public function index(Request $request, Form $form)
         return response()->json($blocks->values()->toArray());
     }
 
+    /**
+     * Create a form block
+     *
+     * This endpoint creates a new form block for the specified form.
+     */
     public function create(Form $form, Request $request)
     {
         $this->authorize('update', $form);
@@ -46,6 +60,11 @@ public function create(Form $form, Request $request)
         return response()->json($block->fresh(), 201);
     }
 
+    /**
+     * Update a form block
+     *
+     * This endpoint updates a form block for the specified form.
+     */
     public function update(FormBlockUpdateRequest $request, FormBlock $block)
     {
         $this->authorize('update', $block);
@@ -58,6 +77,11 @@ public function update(FormBlockUpdateRequest $request, FormBlock $block)
         return response()->json($block, 200);
     }
 
+    /**
+     * Delete a form block
+     *
+     * This endpoint deletes a form block for the specified form.
+     */
     public function delete(Request $request, FormBlock $block)
     {
         $this->authorize('delete', $block);

app/Http/Controllers/Api/FormBlockInteractionController.php

@@ -8,9 +8,20 @@
 use App\Models\FormBlockInteraction;
 use Illuminate\Http\Request;
 use Illuminate\Validation\Rule;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
+#[Group('Form Block Interactions')]
+#[Authenticated]
 class FormBlockInteractionController extends Controller
 {
+    /**
+     * Create a new form block interaction
+     *
+     * This endpoint creates a new form block interaction. Please note that the type of the interaction must be compatible with the type of the form block. If you create a button interaction, the form block must be of type "button".
+     *
+     * You can get a mapping of the available types via the [/api/form-blocks/mapping](#endpoints-GETapi-form-blocks-mapping) endpoint
+     */
     public function create(Request $request, FormBlock $block)
     {
         $this->authorize('update', $block);
@@ -29,6 +40,11 @@ public function create(Request $request, FormBlock $block)
         return response()->json($interaction->fresh(), 201);
     }
 
+    /**
+     * Update a form block interaction
+     *
+     * This endpoint updates a form block interaction.
+     */
     public function update(Request $request, FormBlockInteraction $interaction)
     {
         $this->authorize('update', $interaction);
@@ -47,6 +63,11 @@ public function update(Request $request, FormBlockInteraction $interaction)
         return response()->json($interaction, 200);
     }
 
+    /**
+     * Delete a form block interaction
+     *
+     * This endpoint deletes a form block interaction.
+     */
     public function delete(Request $request, FormBlockInteraction $interaction)
     {
         $this->authorize('delete', $interaction);

app/Http/Controllers/Api/FormBlockInteractionSequenceController.php

@@ -5,9 +5,18 @@
 use App\Http\Controllers\Controller;
 use App\Models\FormBlock;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
 class FormBlockInteractionSequenceController extends Controller
 {
+    /**
+     * Update the sequence of form block interactions
+     *
+     * This endpoint updates the sequence of form block interactions. The sequence means the order in which the interacctions are returned in the storyboard
+     */
+    #[Group('Form Block Interactions')]
+    #[Authenticated]
     public function __invoke(Request $request, FormBlock $block)
     {
         $this->authorize('update', $block);

app/Http/Controllers/Api/FormBlockMappingController.php

@@ -5,9 +5,18 @@
 use App\Enums\FormBlockType;
 use App\Http\Controllers\Controller;
 use App\Models\FormBlock;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
 class FormBlockMappingController extends Controller
 {
+    /**
+     * Get the form block mapping
+     *
+     * This endpoint returns the mapping between the form block types and the interaction types.
+     */
+    #[Group('Utilities')]
+    #[Authenticated]
     public function __invoke()
     {
         $mapping = [];

app/Http/Controllers/Api/FormBlockSequenceController.php

@@ -5,9 +5,18 @@
 use App\Http\Controllers\Controller;
 use App\Models\Form;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
 class FormBlockSequenceController extends Controller
 {
+    /**
+     * Update the sequence of form blocks
+     *
+     * This endpoint updates the sequence of form blocks. The sequence means the order in which the blocks are returned in the storyboard.
+     */
+    #[Group('Form Blocks')]
+    #[Authenticated]
     public function __invoke(Request $request, Form $form)
     {
         $this->authorize('update', $form);

app/Http/Controllers/Api/FormController.php

@@ -5,9 +5,19 @@
 use App\Http\Controllers\Controller;
 use App\Models\Form;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Endpoint;
+use Knuckles\Scribe\Attributes\Group;
 
+#[Group('Forms')]
+#[Authenticated]
 class FormController extends Controller
 {
+    /**
+     * List all forms
+     *
+     * This endpoint returns all forms of the authenticated user.
+     */
     public function index(Request $request)
     {
         $request->validate([
@@ -22,6 +32,11 @@ public function index(Request $request)
         return response()->json($forms);
     }
 
+    /**
+     * Create a new form
+     *
+     * This endpoint creates a new form for the authenticated user.
+     */
     public function create(Request $request)
     {
         $form = Form::create([
@@ -34,6 +49,11 @@ public function create(Request $request)
         return response()->json($form);
     }
 
+    /**
+     * Get a form
+     *
+     * This endpoint returns all meta data of a form, like title, description and settings.
+     */
     public function show(Request $request, Form $form)
     {
         $this->authorize('view', $form);
@@ -45,6 +65,11 @@ public function show(Request $request, Form $form)
         return response()->json($form);
     }
 
+    /**
+     * Update a form
+     *
+     * This endpoint can update the forms basic data, like title, description and settings
+     */
     public function update(Request $request, Form $form)
     {
         $this->authorize('update', $form);
@@ -96,6 +121,11 @@ public function update(Request $request, Form $form)
         return response()->json($form, 200);
     }
 
+    /**
+     * Delete a form
+     *
+     * This endpoint soft deletes a form and all its data. When a form is deleted, it can be restored within 30 days.
+     */
     public function delete(Form $form)
     {
         $this->authorize('delete', $form);

app/Http/Controllers/Api/FormImagesController.php

@@ -9,9 +9,18 @@
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
 
+#[Group('Form Images')]
+#[Authenticated]
 class FormImagesController extends Controller
 {
+    /**
+     * Upload a new form image
+     *
+     * This endpoint uploads a new image for the specified form. This can be a logo or a background image.
+     */
     public function store(FormImageRequest $request, Form $form)
     {
         $this->authorize('update', $form);
@@ -37,6 +46,11 @@ public function store(FormImageRequest $request, Form $form)
         return response()->json($form, 201);
     }
 
+    /**
+     * Delete a form image
+     *
+     * This endpoint deletes an image for the specified form.
+     */
     public function delete(Request $request, Form $form)
     {
         $this->authorize('update', $form);

app/Http/Controllers/Api/FormSubmissionsController.php

@@ -4,10 +4,22 @@
 
 use App\Http\Controllers\Controller;
 use App\Http\Resources\FormSessionResource;
+use App\Models\FormSession;
 use Illuminate\Http\Request;
+use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Group;
+use Knuckles\Scribe\Attributes\ResponseFromApiResource;
 
 class FormSubmissionsController extends Controller
 {
+    /**
+     * Get form submissions
+     *
+     * This endpoint returns all form submissions for a form.
+     */
+    #[Group('Form Submissions')]
+    #[ResponseFromApiResource(FormSessionResource::class, FormSession::class, status: 200, collection: true, with: ['formSessionResponses', 'webhooks'])]
+    #[Authenticated]
     public function __invoke(Request $request, string $uuid)
     {
         try {