Improve creating a data source guide (#32)

* Minor fixes + update outdated screenshots

* Add details on how to use Swagger UI for testing the data source

* Update src/routes/guides/building-a-data-source/+page.svelte

Co-authored-by: Janne Enberg <janne.enberg@lietu.net>

* Update src/routes/guides/building-a-data-source/+page.svelte

Co-authored-by: Janne Enberg <janne.enberg@lietu.net>

* Update src/routes/guides/building-a-data-source/+page.svelte

Co-authored-by: Janne Enberg <janne.enberg@lietu.net>

* Run pre-commit

* Reformat manually a bit

Still passes pre-commit

* Fix link

---------

Co-authored-by: Janne Enberg <janne.enberg@lietu.net>

Author: joakimnordling

src/lib/utils.ts

@@ -1,5 +1,5 @@
 export function isInternalLink(url: string): boolean {
   const docsAbsoluteUrl = url.startsWith("https://docs.ioxio.dev/")
-  const relativeUrl = url.startsWith("/")
+  const relativeUrl = url.startsWith("/") || url.startsWith("#")
   return docsAbsoluteUrl || relativeUrl
 }

src/routes/guides/building-a-data-source/+page.svelte

@@ -36,7 +36,7 @@
     protocol.
   </li>
   <SectionTitle title="Choosing a data definition for your source" />
-  <p>You can find the available <em>Data definitions</em> via menu.</p>
+  <p>You can find the available <em>Data definitions</em> in the menu.</p>
   <GuideImage compact img={images.DEFINITIONS} />
   <p>
     If there is no definition for the type of data you want to provide, you can create your own
@@ -113,7 +113,7 @@
     Some dataspaces have moderated group creation. If the page has a notice saying so, and you are
     unable to create the group yourself, please follow the instructions visible in the page to get a
     group. Note, that if your organization already has a group, you will need to ask your group's
-    administrator to invite you to the existing group.
+    owner to invite you to the existing group.
   </p>
   <h3>Add your data source</h3>
   <p>
@@ -152,10 +152,6 @@
     <li>
       <b>No access control</b> - The dataspace will allow anyone to request data from the data source.
     </li>
-    <li>
-      <b>Self-managed API keys</b> - <em>X-API-Key</em> header will be required to be present, but its
-      contents will not be verified by the dataspace.
-    </li>
     <li>
       <b>Dataspace verified API tokens</b> - The <em>X-API-Key</em> header will be required and
       verified by the dataspace. Once you save the data source with this setting you can manage
@@ -184,6 +180,12 @@
     need to add your own group explicitly, but if you want to add other groups for testing purposes,
     - click <em>+ Add</em>, type in the name of the group, click <em>+ Add</em> again.
   </p>
+  <p>
+    To test your data source, you can either follow the more in-depth steps in the next
+    <A href="#test-your-data-source">Test your data source</A> section or head to the
+    <A href="#test-your-data-source-using-swagger-ui">Test your data source using Swagger UI</A> section
+    a bit further down for a simpler and quicker approach.
+  </p>
   <SectionTitle title="Test your data source" />
   <p>
     You should now be able to test your own data source by querying it through the product gateway.
@@ -247,6 +249,53 @@
     source edit page after a short while:
   </p>
   <GuideImage img={images.ERRORS} />
+
+  <SectionTitle title="Test your data source using Swagger UI" />
+  <p>The quickest and easiest way to test your data source is using these steps with Swagger UI.</p>
+  <p>
+    From the edit data source view, you can quickly jump to the Access control keys for your source
+    by pressing the key icon in the list of <em>Allowed groups</em> section.
+  </p>
+  <GuideImage img={images.ALLOWED_GROUPS_KEY} />
+  <p>
+    Alternatively you can open the <em>Access control keys</em> from the menu and open the details for
+    your own source.
+  </p>
+  <p>
+    On the View access control keys page press the <em>Generate API token</em> button. This will for
+    convenience use one of the long-lived access control keys and generate a short lived API token (typically
+    valid for about an hour) and display it to you for easier testing.
+  </p>
+  <GuideImage img={images.GENERATE_API_TOKEN_BUTTON} />
+  <p>
+    Copy the generated API token, make a note of the source value and open the <em>Swagger UI</em> link.
+  </p>
+  <GuideImage img={images.COPY_API_TOKEN_AND_OPEN_SWAGGER_UI} />
+  <p>
+    Press the <em>Try it out</em> button in Swagger UI.
+  </p>
+  <GuideImage img={images.SWAGGER_UI_TRY_IT_OUT} />
+  <p>
+    Enter the name of the source (the one you were requested earlier to make a note of) and paste in
+    the API token you copied in the <em>x-api-key</em> field. Do any changes you want to the request
+    body and press the
+    <em>Execute</em> button to perform the request.
+  </p>
+  <GuideImage img={images.SWAGGER_UI_FILLED_IN_FORM} />
+  <p>
+    Swagger UI will in the <em>Responses</em> section show you the curl command corresponding to the
+    request that it made and also show the status code and body of the response.
+  </p>
+  <GuideImage img={images.SWAGGER_UI_RESPONSE} />
+  <p>
+    Check the status and response is as you expect or in case of an error check the details in the
+    error message. Please note that the API tokens are typically valid for only about an hour, so if
+    you do a lot of testing you might encounter the
+    <em>API token is not valid for this source or it has expired</em>
+    message, which means you need to go back to the Access control keys page and generate a fresh one
+    to use.
+  </p>
+
   <SectionTitle title="Publish the data source" />
   <p>
     When you've verified the data source works as intended you can publish the data source by

src/routes/guides/images.json

@@ -14,6 +14,10 @@
       "src": "/guides/building-a-data-source/allowed_groups.png",
       "alt": "Allowed groups section in data source edit form"
     },
+    "ALLOWED_GROUPS_KEY": {
+      "src": "/guides/building-a-data-source/allowed_groups_key.png",
+      "alt": "Allowed groups section in data source edit form with arrow pointing at the key icon."
+    },
     "API_TOKEN": {
       "src": "/guides/building-a-data-source/api_token.png",
       "alt": "Access control keys of a data source"
@@ -41,6 +45,26 @@
     "SOURCE_ACCESS_CONTROL": {
       "src": "/guides/building-a-data-source/source_access_control.png",
       "alt": "Data source in the list of data sources with Dataspace verified API keys"
+    },
+    "GENERATE_API_TOKEN_BUTTON": {
+      "src": "/guides/building-a-data-source/generate_api_token_button.png",
+      "alt": "Generate API token button on the view access control keys page."
+    },
+    "COPY_API_TOKEN_AND_OPEN_SWAGGER_UI": {
+      "src": "/guides/building-a-data-source/copy_api_token_and_open_swagger_ui.png",
+      "alt": "Arrows pointing at the copy API token button, the source and the Swagger UI link."
+    },
+    "SWAGGER_UI_TRY_IT_OUT": {
+      "src": "/guides/building-a-data-source/swagger_ui_try_it_out.png",
+      "alt": "Arrow pointing at the Try it out button in Swagger UI."
+    },
+    "SWAGGER_UI_FILLED_IN_FORM": {
+      "src": "/guides/building-a-data-source/swagger_ui_filled_in_form.png",
+      "alt": "Swagger UI form with arrows pointing at the source and x-api-key input fields, as well as the Request body textarea and Execute button."
+    },
+    "SWAGGER_UI_RESPONSE": {
+      "src": "/guides/building-a-data-source/swagger_ui_response.png",
+      "alt": "Swagger UI Responses section showing the curl command and server response."
     }
   },
   "BUILD_APP": {