Add docs for using problem4j-core in a non-framework setup

Author: damianmalczewski

docs/02-problem4j-core.md …-core/01-setting-up-and-configuration.mddocs/02-problem4j-core.md renamed to docs/01-problem4j-core/01-setting-up-and-configuration.md docs/02-problem4j-core.md renamed to docs/01-problem4j-core/01-setting-up-and-configuration.md

@@ -1,17 +1,10 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 ---
 
-# Problem4J Core
+# Setting Up & Configuration
 
-Problem4J Core provides a framework-agnostic set of features to be used in implementing framework-specific features by
-other modules. There are two primary ways of throwing exception with `Problem`.
-
-1. Throw a `ProblemException`.
-2. Throw exception annotated with `@ProblemMapping`.
-
-Following chapters touch also other aspects, such as `ProblemContext` and how to approach altering `Problem` objects,
-if they are immutable.
+Setting up dependencies for using Problem4J Core library.
 
 ## Dependency
 
@@ -35,7 +28,18 @@ higher is required to use this library.
    }
     ```
 
-## Throw a `ProblemException`
+## Usage
+
+Problem4J Core provides a framework-agnostic set of features to be used in implementing framework-specific features by
+other modules. There are two primary ways of throwing exception with `Problem`.
+
+1. Throw a `ProblemException`.
+2. Throw exception annotated with `@ProblemMapping`.
+
+Following chapters touch also other aspects, such as `ProblemContext` and how to approach altering `Problem` objects,
+if they are immutable.
+
+### Throw a `ProblemException`
 
 The most basic method is to throw a `ProblemException` or its subclass.
 
@@ -83,7 +87,7 @@ static Problem Problem.of(URI type, String title, int status);
 static Problem Problem.of(URI type, String title, int status, @Nullable String detail);
 ```
 
-## Throw exception annotated with `@ProblemMapping`
+### Throw exception annotated with `@ProblemMapping`
 
 If an exception is annotated with `@ProblemMapping`, extracting the underlying `Problem` from it requires a bit of
 setup first. Fields such as `type`, `title`, `detail` and `instance` allow to interpolate fields from exception object
@@ -137,7 +141,7 @@ try {
 }
 ```
 
-## Including `ProblemContext` in `@ProblemMapping`-annotated exception
+### Including `ProblemContext` in `@ProblemMapping`-annotated exception
 
 `ProblemMapper` allows passing `ProblemContext` instance as an additional argument to `toProblemBuilder` method. Such
 context allows to pass additional data for `@ProblemMapping` fields interpolation.
@@ -184,7 +188,7 @@ try {
 }
 ```
 
-## Modifying `Problem` objects
+### Modifying `Problem` objects
 
 `Problem` objects are immutable. In order to change any of its values, you are required to create a new `Problem`
 object. For that purpose, consider using `toBuilder()` method.

docs/01-problem4j-core/02-using-it-from-scratch.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+---
+
+# Using it from scratch
+
+An example of setting up with an actual HTTP server.
+
+The primary integration provided by this library orbits around Spring Boot. However, the Problem4J libraries are fully
+featured to work in any environment.
+
+## Integration example for Javalin
+
+This chapter is a quick introduction to using Problem4J in a non-Spring Java application, using [Javalin][javalin]
+library for HTTP server functionality.
+
+Note that this example also assumes, for JSON serialization, that you use Jackson (`JsonMapper`) in either v2 or v3 and
+the compatible [Problem4J Jackson](../problem4j-jackson) module.
+
+```java
+JsonMapper jsonMapper = new JsonMapper.Builder().findAndAddModules().build();
+ProblemMapper problemMapper = ProblemMapper.create();
+
+Javalin app = Javalin.create();
+
+app.get("/hello", ctx -> {
+    throw new ProblemException(
+        Problem.of("Hello Error", 400, "something went wrong with /hello endpoint"));
+});
+
+app.exception(ProblemException.class, (ex, ctx) -> {
+    Problem problem = ex.getProblem();
+
+    String json = jsonMapper.writeValueAsString(problem);
+    ctx.status(problem.getStatus()).result(json).contentType(Problem.CONTENT_TYPE);
+});
+
+app.exception(Exception.class, (ex, ctx) -> {
+    Problem problem = Problem.of(500);
+
+    if (problemMapper.isMappingCandidate(ex)) {
+        problem = problemMapper.toProblemBuilder(ex).build();
+    }
+
+    String json = jsonMapper.writeValueAsString(problem);
+    ctx.status(problem.getStatus()).result(json).contentType(Problem.CONTENT_TYPE);
+});
+
+app.start(7676);
+```
+
+The above example demonstrates support for both throwing `ProblemException` instances and `@ProblemMapping`-annotated
+exceptions. The former is a simple wrapper around `Problem` objects, while the latter relies on the `ProblemMapper` to
+convert exceptions into `Problem` instances.
+
+[javalin]: https://javalin.io/

docs/01-problem4j-core/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Problem4J Core",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn about Problem4J Core - the base, framework-agnostic features of Problem4J."
+  }
+}

docusaurus.config.ts

@@ -88,7 +88,7 @@ const config: Config = {
         //   label: 'Docs',
         // },
         {to: '/docs/intro', label: 'Intro', position: 'left'},
-        {to: '/docs/problem4j-core', label: 'Problem4J Core', position: 'left'},
+        {to: '/docs/category/problem4j-core', label: 'Problem4J Core', position: 'left'},
         {to: '/docs/problem4j-jackson', label: 'Problem4J Jackson', position: 'left'},
         {to: '/docs/category/problem4j-spring', label: 'Problem4J Spring', position: 'left'},
         {to: '/blog', label: 'Blog', position: 'left'},
@@ -111,7 +111,7 @@ const config: Config = {
             },
             {
               label: 'Problem4J Core',
-              to: '/docs/problem4j-core',
+              to: '/docs/category/problem4j-core',
             },
             {
               label: 'Problem4J Jackson',