From 4ad0efee760b6a2b360af030748c27232b2634d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Wed, 3 Jun 2026 20:15:51 +0200 Subject: [PATCH] docs(website): Fix documentation links and format --- docs/website/docs/endpoints.md | 22 +++++++++++----------- docs/website/docs/failures-arrow.md | 16 ++++++++-------- docs/website/docs/failures.md | 10 +++++----- docs/website/docs/parameters.md | 2 +- docs/website/docs/resources.md | 8 ++++---- docs/website/docs/setup.md | 16 ++++++++-------- 6 files changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/website/docs/endpoints.md b/docs/website/docs/endpoints.md index fb636b4..275d30f 100644 --- a/docs/website/docs/endpoints.md +++ b/docs/website/docs/endpoints.md @@ -1,6 +1,6 @@ # Declare fullstack Ktor endpoints with Spine -> Reference: [`AnyEndpoint`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-any-endpoint) +> Reference: [`AnyEndpoint`](api/api/opensavvy.spine.api/-any-endpoint/index.md) Once you have described the [resources](resources.md) of your API, you can declare endpoints. Each endpoint is a combination of a path, an HTTP method, and more optional information, like the body type. @@ -19,13 +19,13 @@ The name of the variable itself doesn't matter. For the remainder of this page, the enclosing resource is omitted from code samples for conciseness. !!! danger "Do not explicitly write the type of your endpoints" -In Kotlin, we have the choice of explicitly writing a variable's type, or letting the compiler infer it. -```kotlin -val get: SomeTypeHere by get() -``` -However, this should be avoided for Spine endpoints. We recommend letting the compiler infer the type. If you write the type explicitly, it is likely that your code will not compile anymore when new versions of Spine are released. If you're curious, you can learn more [here](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-any-endpoint/index.md#the-trick). + In Kotlin, we have the choice of explicitly writing a variable's type, or letting the compiler infer it. + ```kotlin + val get: SomeTypeHere by get() + ``` + However, this should be avoided for Spine endpoints. We recommend letting the compiler infer the type. If you write the type explicitly, it is likely that your code will not compile anymore when new versions of Spine are released. If you're curious, you can learn more [here](api/api/opensavvy.spine.api/-any-endpoint/index.md#the-trick). - If you really must write the type of an endpoint (for example if you write an introspection function that prints all endpoints), you should use the `AnyEndpoint` type, which has access to all endpoint informatino but without type safety. + If you really must write the type of an endpoint (for example if you write an introspection function that prints all endpoints), you should use the `AnyEndpoint` type, which has access to all endpoint information but without type safety. ## HTTP method @@ -96,10 +96,10 @@ val createUser by post() .response() ``` -1. [`request`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-any-endpoint/-builder/request.md) allows declaring the type of the data sent by the client. The value will go through Ktor's usual content negotiation, following your existing configuration. -2. [`response`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-any-endpoint/-builder/response.md) allows declaring the type of the data sent by the server. The value will go through Ktor's usual content negotiation, following your existing configuration. +1. [`response`](api/api/opensavvy.spine.api/-any-endpoint/-builder/index.md#response) allows declaring the type of the data sent by the server. The value will go through Ktor's usual content negotiation, following your existing configuration. +2. [`request`](api/api/opensavvy.spine.api/-any-endpoint/-builder/index.md#request) allows declaring the type of the data sent by the client. The value will go through Ktor's usual content negotiation, following your existing configuration. -On the server-side, the request body is accessible through the [`body`](api/-server-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.server/-typed-response-scope/body.md) variable, and the response body can be sent with the function [`respond`](api/-server-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.server/respond.md): +On the server-side, the request body is accessible through the [`body`](api/server/opensavvy.spine.server/-typed-response-scope/index.md#body) variable, and the response body can be sent with the function [`respond`](api/server/opensavvy.spine.server/-typed-response-scope/index.md#respond): ```kotlin route(Users.createUser) { @@ -109,7 +109,7 @@ route(Users.createUser) { } ``` -On the client-side, the request body is passed as the second argument of the function [`request`](api/-client-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.client/request.md), and the response is acquired via the result of [`bodyOrThrow`](api/-client-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.client/body-or-throw.md): +On the client-side, the request body is passed as the second argument of the function [`request`](api/client/opensavvy.spine.client/request.md), and the response is acquired via the result of [`bodyOrThrow`](api/client/opensavvy.spine.client/-spine-response/index.md#bodyorthrow): ```kotlin val user = client.request(Users.createUser, UserCreationDto(name = "Bob")) diff --git a/docs/website/docs/failures-arrow.md b/docs/website/docs/failures-arrow.md index 941b11c..64083c1 100644 --- a/docs/website/docs/failures-arrow.md +++ b/docs/website/docs/failures-arrow.md @@ -1,6 +1,6 @@ # Declare Ktor failures with Spine and Arrow -Spine provides helper functions for the [Arrow Typed Errors library](https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/). They are based on the `Raise` DSL and [context parameters](https://kotlinlang.org/docs/context-parameters.html), which you may need to [enable](https://kotlinlang.org/docs/context-parameters.html#how-to-enable-context-parameters). +Spine provides helper functions for the [Arrow Typed Errors library](https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/). They are based on the `Raise` DSL and [context parameters](https://kotlinlang.org/docs/context-parameters.html), a new feature in [Kotlin 2.4.0](https://kotlinlang.org/docs/whatsnew24.html). ## Declaring failures @@ -22,7 +22,7 @@ Add a dependency on the `server-arrow` module: } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) === "Kotlin Multiplatform" @@ -42,9 +42,9 @@ Add a dependency on the `server-arrow` module: } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) -When declaring routes, replace `route` by `routeWithRaise`: +When declaring routes, replace `route` by [`routeWithRaise`](api/server-arrow/opensavvy.spine.server.arrow/route-with-raise.md): the Arrow module adds: @@ -76,7 +76,7 @@ routeWithRaise(Users.User.edit) { ``` ??? info "Raise in Ktor endpoints without Spine" -If you want to use the `Raise` DSL with Ktor, but don't want to use Spine, you can use our module `server-arrow-independent` which adds the function [`raise`](api/-server-side%20-arrow%20helpers/opensavvy.spine.server.arrow.independent/raise.md) to regular Ktor endpoints. + If you want to use the `Raise` DSL with Ktor, but don't want to use Spine, you can use our module `server-arrow-independent` which adds the function [`raise`](api/server-arrow-independent/opensavvy.spine.server.arrow.independent/raise.md) to regular Ktor endpoints. ## Client-side @@ -94,7 +94,7 @@ Add a dependency on the `client-arrow` module: } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) === "Kotlin Multiplatform" @@ -114,9 +114,9 @@ Add a dependency on the `client-arrow` module: } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) -In addition to `.bodyOrThrow()`, `.bodyOrNull()` and `.handle()` ([learn more](failures.md#client-side)), this module adds the [`.body()`](api/-client-side%20typesafe%20-spine%20schema%20usage%20(with%20-arrow%20typed%20errors)/opensavvy.spine.client.arrow/body.md) function which raises each failure. +In addition to `.bodyOrThrow()`, `.bodyOrNull()` and `.handle()` ([learn more](failures.md#client-side)), this module adds the [`.body()`](api/client-arrow/opensavvy.spine.client.arrow/body.md) function which raises each failure. ```kotlin context(Raise) diff --git a/docs/website/docs/failures.md b/docs/website/docs/failures.md index 4a40a4f..57e508e 100644 --- a/docs/website/docs/failures.md +++ b/docs/website/docs/failures.md @@ -1,6 +1,6 @@ # Declare Ktor failures with Spine -> Reference: [`FailureSpec`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-failure-spec) +> Reference: [`FailureSpec`](api/api/opensavvy.spine.api/-failure-spec/index.md) ## Declaring failures @@ -48,7 +48,7 @@ data class InvalidAge(val userId: String, val explain: String) : CannotProcessUs > If you use [Arrow Typed Errors](https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/), you may be interested in [our dedicated support](failures-arrow.md). -On the server-side, Spine adds the [`fail()`](api/-server-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.server/fail.md) method to fail with one of the declared failures: +On the server-side, Spine adds the [`fail()`](api/server/opensavvy.spine.server/-typed-response-scope/index.md#fail) method to fail with one of the declared failures: ```kotlin route(Users.User.patch) { @@ -74,9 +74,9 @@ Calling `fail()` interrupts the function, no further code is executed. On the client-side, users have the choice between: -- Throwing an exception on any kind of failure with [`bodyOrThrow`](api/-client-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.client/body-or-throw.md). -- Treating all failures as `#!kotlin null` with [`bodyOrNull`](api/-client-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.client/body-or-null.md). -- Handle each failure separately with [`handle`](api/-client-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.client/handle.md). +- Throwing an exception on any kind of failure with [`bodyOrThrow`](api/client/opensavvy.spine.client/-spine-response/index.md#bodyorthrow). +- Treating all failures as `#!kotlin null` with [`bodyOrNull`](api/client/opensavvy.spine.client/-spine-response/index.md#bodyornull). +- Handle each failure separately with [`handle`](api/client/opensavvy.spine.client/-spine-response/index.md#handle). The `handle` method accepts one handler for each declared failure. diff --git a/docs/website/docs/parameters.md b/docs/website/docs/parameters.md index a113199..a0af8e0 100644 --- a/docs/website/docs/parameters.md +++ b/docs/website/docs/parameters.md @@ -1,6 +1,6 @@ # Declare query parameters with Spine -> Reference: [`Parameters`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-parameters) +> Reference: [`Parameters`](api/api/opensavvy.spine.api/-parameters/index.md) With Spine, query parameters can be declared in your multiplatform code and type-safely referred to on the server and client side. diff --git a/docs/website/docs/resources.md b/docs/website/docs/resources.md index a5ca5a8..b6f94c5 100644 --- a/docs/website/docs/resources.md +++ b/docs/website/docs/resources.md @@ -66,7 +66,7 @@ Here is an example that describes the endpoints: ## The root resource -> Reference: [`RootResource`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-root-resource) +> Reference: [`RootResource`](api/api/opensavvy.spine.api/-root-resource/index.md) The root resource is the root of a specific API. @@ -80,7 +80,7 @@ object Api3 : RootResource("v3") ## Static resources -> Reference: [`StaticResource`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-static-resource) +> Reference: [`StaticResource`](api/api/opensavvy.spine.api/-static-resource/index.md) A static resource represents a path within another resource. Each static resource must refer to its direct parent in the constructor call. @@ -107,7 +107,7 @@ To refer to a static resource on the client-side, you can use the slash notation ## Dynamic resources -> Reference: [`DynamicResource`](api/-multiplatform%20-ktor%20schema%20declaration/opensavvy.spine.api/-dynamic-resource) +> Reference: [`DynamicResource`](api/api/opensavvy.spine.api/-dynamic-resource/index.md) Dynamic resources represent a segment that can have multiple different values at runtime. Typically, this is used for the ID of a resource. @@ -132,7 +132,7 @@ object V2 : RootResource("v2") { To refer to a dynamic resource on the server-side, you can use the regular Kotlin `.` notation: `Api2.Users.User.Friends.Friend`. -When implementing a dynamic resource on the server-side, you can access the value of the path parameter using the method [`idOf`](api/-server-side%20typesafe%20-spine%20schema%20usage/opensavvy.spine.server/-typed-response-scope/id-of.md): +When implementing a dynamic resource on the server-side, you can access the value of the path parameter using the method [`idOf`](api/server/opensavvy.spine.server/-typed-response-scope/index.md#idof): ```kotlin route(Api2.Users.User.Friends.Friend) { diff --git a/docs/website/docs/setup.md b/docs/website/docs/setup.md index 8b08080..7a6c76a 100644 --- a/docs/website/docs/setup.md +++ b/docs/website/docs/setup.md @@ -47,7 +47,7 @@ For now, we will edit the shared module (called `shared` in our example). Start } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) Then, create the file `src/main/kotlin/Api.kt`. @@ -69,7 +69,7 @@ For now, we will edit the shared module (called `shared` in our example). Start } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) Then, create the file `src/commonMain/kotlin/Api.kt`. @@ -120,7 +120,7 @@ Start by adding the Spine dependency to your server-side module. } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) 2. Ensure the backend module has access to the endpoints we just declared. Then, create the file `src/main/kotlin/Ping.kt`. @@ -144,7 +144,7 @@ Start by adding the Spine dependency to your server-side module. } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) 2. Ensure the backend module has access to the endpoints we just declared. Then, create the file `src/commonMain/kotlin/Ping.kt`. @@ -218,7 +218,7 @@ Finally, we can call these methods on the frontend side. We'll start by declarin } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) 2. Ensure the frontend module has access to the endpoints we declared. Then, create the file `src/main/kotlin/Ping.kt`. @@ -242,7 +242,7 @@ Finally, we can call these methods on the frontend side. We'll start by declarin } ``` - 1. [List of versions](news/) + 1. [List of versions](news/index.md) 2. Ensure the frontend module has access to the endpoints we declared. Then, create the file `src/commonMain/kotlin/Ping.kt`. @@ -356,7 +356,7 @@ Modify the configuration of the backend: Then, create the file `src/commonTest/kotlin/PingTest.kt`. -In this example, we'll use the [Prepared test framework](https://prepared.opensavvy.dev) using the [TestBalloon engine](https://prepared.opensavvy.dev/api-docs/runners/runner-testballoon/index.html) and the [Ktor compatibility module](https://prepared.opensavvy.dev/features/compat-ktor.html), which require additional configuration not shown here. However, you can follow the same steps with any other test framework. +In this example, we'll use the [Prepared test framework](https://prepared.opensavvy.dev) using the [TestBalloon engine](https://prepared.opensavvy.dev/api/runner-testballoon/index.html) and the [Ktor compatibility module](https://prepared.opensavvy.dev/features/compat-ktor.html), which require additional configuration not shown here. However, you can follow the same steps with any other test framework. ```kotlin title="PingTest.kt" package your.app.test @@ -399,7 +399,7 @@ val PingTest by preparedSuite { //(1)! } ``` -1. The `preparedSuite` DSL is the entrypoint for tests declared with [Prepared and TestBalloon](https://prepared.opensavvy.dev/api-docs/runners/runner-testballoon/index.html). If you use another test framework, it will be different. +1. The `preparedSuite` DSL is the entrypoint for tests declared with [Prepared and TestBalloon](https://prepared.opensavvy.dev/api/runner-testballoon/index.html). If you use another test framework, it will be different. 2. The `preparedServer` DSL allows declaring the Ktor TestHost as [a special test fixture](https://prepared.opensavvy.dev/features/compat-ktor.html). If you use another test framework, this is probably replaced by calling the `testApplication {}` function within each test. 3. We always need at least `ContentNegotation`. Notice the import alias, used because we need both server and client negotiation in this file. 4. We can configure the Ktor test host, just like a real server, with the `routing {}` block. To simplify tests, however, we will only register the routes related to the test, instead of registering the entire API. -- 2.51.2