Fix #123 Define a proper documentation for the provisioning flow

flexiapi/app/Http/Controllers/Account/ProvisioningController.php

@@ -32,6 +32,13 @@ use Endroid\QrCode\Writer\PngWriter;
 
 class ProvisioningController extends Controller
 {
+    public function documentation(Request $request)
+    {
+        return view('provisioning.documentation', [
+            'documentation' => markdownDocumentationView('provisioning.documentation_markdown')
+        ]);
+    }
+
     public function qrcode(Request $request, string $provisioningToken)
     {
         $account = Account::withoutGlobalScopes()

flexiapi/app/Http/Controllers/Api/StatisticsCallController.php

@@ -34,7 +34,7 @@ class StatisticsCallController extends Controller
             'from' => 'required|string|max:256',
             'to' => 'required|string|max:256',
             'initiated_at' => 'required|iso_date',
-            'ended_at' => 'iso_date',
+            'ended_at' => 'iso_date|nullable',
             'conference_id' => 'string|nullable',
         ]);
 

flexiapi/resources/views/about.blade.php

@@ -11,7 +11,7 @@
         <p><a href="{{ config('app.terms_of_use_url') }}">Terms and Conditions</a> and <a
                 href="{{ config('app.privacy_policy_url') }}">Privacy policy</a></p>
 
-        <p><a href="{{ route('api') }}">API Documentation</a> and <a href="{{ route('account.documentation') }}">General Documentation</a></p>
+        <p><a href="{{ route('api') }}">API Documentation</a>, <a href="{{ route('provisioning.documentation') }}">Provisioning Documentation</a> and <a href="{{ route('account.documentation') }}">General Documentation</a></p>
 
         <p>GNU General Public Licence v3.0 (Licence)</p>
 

flexiapi/resources/views/api/documentation_markdown.blade.php

@@ -714,45 +714,6 @@ JSON parameters:
 
 The following URLs are **not API endpoints** they are not returning `JSON` content and they are not located under `/api` but directly under the root path.
 
-## Provisioning
-
-When an account is having an available `provisioning_token` it can be provisioned using the two following URL.
-
-### `GET /provisioning`
-
-<span class="badge badge-success">Public</span>
-
-Return the provisioning information available in the liblinphone configuration file (if correctly configured).
-
-### `GET /provisioning/{provisioning_token}?reset_password`
-
-<span class="badge badge-success">Public</span>
-
-Return the provisioning information available in the liblinphone configuration file.
-If the `provisioning_token` is valid the related account information are added to the returned XML. The account is then considered as "provisioned" and those account related information will be removed in the upcoming requests (the content will be the same as the previous url).
-
-If the account is not activated and the `provisioning_token` is valid. The account will be activated.
-
-URL parameters:
-
-* `reset_password` optional, reset the password while doing the provisioning
-
-### `GET /provisioning/qrcode/{provisioning_token}?reset_password`
-
-<span class="badge badge-success">Public</span>
-
-Return a QRCode that points to the provisioning URL.
-
-URL parameters:
-
-* `reset_password` optional, reset the password while doing the provisioning
-
-### `GET /provisioning/me`
-
-<span class="badge badge-info">User</span>
-
-Return the same base content as the previous URL and the account related information, similar to the `provisioning_token` endpoint. However this endpoint will always return those information.
-
 ## Contacts list
 
 ### `GET /contacts/vcard`

flexiapi/resources/views/provisioning/documentation.blade.php

@@ -0,0 +1,8 @@
+@extends('layouts.main', ['welcome' => true])
+
+@section('content')
+    <div>
+        {{-- This view is only a wrapper for the markdown page --}}
+        {!! $documentation !!}
+    </div>
+@endsection

flexiapi/resources/views/provisioning/documentation_markdown.blade.php

@@ -0,0 +1,73 @@
+# Provisioning
+
+Provisioning is a core concept of the FlexiAPI - Linphone clients flow.
+
+## About
+
+### Provisioning XML
+
+```
+<config>
+  <section name="misc">
+    <entry name="contacts-vcard-list" overwrite="true">https://flexiphp.bla/contacts/vcard</entry>
+  </section>
+  ...
+</config>
+```
+
+A provisioning content example
+
+The general idea is to allow the clients to access a unique URL returning a custom XML file containing the following elements:
+
+* <span class="badge badge-success">Public</span> Expose the linphonerc INI file configuration
+* <span class="badge badge-info">User</span> Inject the authentication information to allow the application to authenticate on the server directly if a valid account is detected using the `provisioning` token
+  * A similar information is also injected if an external account is linked to the main one, the application will then be able to authenticate on both accounts at the same time
+* <span class="badge badge-success">Public</span> <span class="badge badge-info">User</span> Using __Custom Hooks__ an admin is also able to have access to the authenticated User internal object and inject custom XML during the provisioning. See the specific section in the `README.md` to learn more about that feature.
+
+### Features
+
+When scanning a provisioning URL with a valid token the server is also:
+
+* <span class="badge badge-info">User</span> Activating the account
+* <span class="badge badge-info">User</span> Reseting the password, generating the new authentication information and returning them (if the `reset_password` parameter is present)
+
+## Endpoints
+
+When an account is having an available `provisioning_token` it can be provisioned using the following URLs.
+
+### `GET /provisioning`
+
+<span class="badge badge-success">Public</span>
+
+Return the provisioning information available in the liblinphone configuration file (if correctly configured).
+
+### `GET /provisioning/{provisioning_token}?reset_password`
+
+<span class="badge badge-success">Public</span>
+
+Return the provisioning information available in the liblinphone configuration file.
+If the `provisioning_token` is valid the related account information are added to the returned XML. The account is then considered as "provisioned" and those account related information will be removed in the upcoming requests (the content will be the same as the previous url).
+
+If the account is not activated and the `provisioning_token` is valid the account will be activated.
+
+URL parameters:
+
+* `reset_password` optional, reset the password while doing the provisioning
+
+### `GET /provisioning/qrcode/{provisioning_token}?reset_password`
+
+<span class="badge badge-success">Public</span>
+
+Return a QRCode that points to the provisioning URL.
+
+URL parameters:
+
+* `reset_password` optional, reset the password while doing the provisioning
+
+### `GET /provisioning/me`
+
+<span class="badge badge-info">User</span>
+
+Authenticated endpoint, see [API About & Auth]({{ route('api') }}#about--auth)
+
+Return the same base content as the previous URL and the account related information, similar to the `provisioning_token` endpoint. However this endpoint will always return those information.

flexiapi/routes/web.php

@@ -60,6 +60,7 @@ Route::group(['middleware' => 'auth.digest_or_key'], function () {
 });
 
 Route::name('provisioning.')->prefix('provisioning')->controller(ProvisioningController::class)->group(function () {
+    Route::get('documentation', 'documentation')->name('documentation');
     Route::get('auth_token/{auth_token}', 'authToken')->name('auth_token');
     Route::get('qrcode/{provisioning_token}', 'qrcode')->name('qrcode');
     Route::get('{provisioning_token?}', 'show')->name('show');