diff --git a/docs/README.md b/docs/README.md index 1add137e1..2cd6ac033 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ make managed 2. Create the full site ```bash -make local +make local open ``` This command will execute a Docker-based build process that compiles the documentation. The generated documentation will be output to the `target/site` directory. diff --git a/docs/src/modules/ROOT/pages/index.adoc b/docs/src/modules/ROOT/pages/index.adoc index c771624f4..fc668e4dd 100644 --- a/docs/src/modules/ROOT/pages/index.adoc +++ b/docs/src/modules/ROOT/pages/index.adoc @@ -53,12 +53,15 @@ Akka's event-sourced model is fundamentally streaming-based, providing a robust == Getting Started with Akka There are multiple ways to get started with Akka. -* *Deploy, scale, and replicate a service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io]. -* *Learn* the Akka xref:concepts:architecture-model.adoc[] for architects and developers. -* *Learn* the Akka xref:concepts:deployment-model.adoc[] for operators. -* *Learn* the Akka xref:concepts:development-process.adoc[] -* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images. xref:java:running-locally.adoc[] -* *Learn how to implement a "Hello World" service.* xref:java:author-your-first-service.adoc[] -* *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[] +* Hands-on +** *Deploy, scale, and replicate a pre-built service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io]. +** *Implement a "Hello World" service.* xref:java:author-your-first-service.adoc[]. +** *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[]. + +* Understand +** ... the Akka xref:concepts:architecture-model.adoc[] for architects and developers. +** ... the Akka xref:concepts:deployment-model.adoc[] for operators. +** ... the Akka xref:concepts:development-process.adoc[]. +* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images. See xref:java:running-locally.adoc[]. * *Setup* CI/CD pipelines, external Docker repositories, external messaging brokers, or 3rd party observability. See xref:operations:index.adoc[Operating Services] for more information. diff --git a/docs/src/modules/java/pages/author-your-first-service.adoc b/docs/src/modules/java/pages/author-your-first-service.adoc index b0c0e59bc..60deccb4f 100644 --- a/docs/src/modules/java/pages/author-your-first-service.adoc +++ b/docs/src/modules/java/pages/author-your-first-service.adoc @@ -16,7 +16,7 @@ NOTE: If you'd rather skip past this and want to review an already completed app == Prerequisites -include::ROOT:partial$cloud-dev-prerequisites.adoc[] +include::ROOT:partial$local-dev-prerequisites.adoc[] == Generate and build the skeleton project @@ -152,27 +152,18 @@ curl localhost:9000/hello/hello/Bob/30 === Request body === -To accept an HTTP JSON body, specify a parameter that is a class that https://github.com/FasterXML/jackson?tab=readme-ov-file#what-is-jackson[Jackson] can deserialize: +To accept an HTTP JSON body, specify a parameter that is a Java record. [source,java] .HelloWorldEndpoint.java ---- include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=request-body] ---- -<1> A class that Jackson can serialize and deserialize to JSON +<1> The record will serialized and deserialized as JSON <2> A parameter of the request body type <3> When combining request body with path variables <4> The body must come last in the parameter list -Additionally, the request body parameter can be of the following types: - - * `String` for any request with a text content type, the body decoded into a string - * `java.util.List` where `T` is a type Jackson can deserialize, accepts a JSON array. - * `akka.http.javadsl.model.HttpEntity.Strict` for the entire request body as bytes together with the content type for - arbitrary payload handling. - * `akka.http.javadsl.model.HttpRequest` for a low level, streaming representation of the entire request - including headers. See xref:http-endpoints.adoc#_low_level_requests[] below for more details - You can now call these commands as well [source, command line] ---- @@ -182,25 +173,14 @@ curl -i -XPOST -H "Content-Type: application/json" localhost:9000/hello/hello -d === Response body === -To return response with JSON, the return value can be a class that Jackson can serialize: +To return response with JSON, the return value can be a record that gets serialized as JSON: [source,java] .HelloWorldEndpoint.java ---- include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=response-body] ---- -<1> Returning an object that Jackson can serialize into JSON - -In addition to an object that can be turned to JSON, a request handler can return the following: - - * `null` or `void` to return an empty body. - * `String` to return a UTF-8 encoded `text/plain` HTTP response. - * `CompletionStage` to respond based on an asynchronous result. - ** When the completion stage is completed with a `T` it is - turned into a response. - ** If it is instead failed, the failure leads to an error response according to - the error handling explained in xref:http-endpoints.adoc#_error_responses[error responses]. - * `akka.http.javadsl.model.HttpResponse` for complete control over the response, see xref:http-endpoints.adoc#_low_level_responses[] below +<1> Returning a record that gets serialized as JSON [source, command line] ---- @@ -208,4 +188,4 @@ curl localhost:9000/hello/hello/Bob/30 ---- == Next steps -Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application. +Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application and learn how to deploy it to https://console.akka.io[akka.io].