guide: produces XML (micronaut-projects#1416)

* guide: produces XML

* Whitespace, license and imports

* change category

* Add note about Serde does not support XML

---------

Co-authored-by: Tim Yates <[email protected]>

guides/micronaut-produces-xml/java/src/main/java/example/micronaut/Book.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2017-2024 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.micronaut;
+
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;
+import io.micronaut.core.annotation.Introspected;
+
+@Introspected // <1>
+@JacksonXmlRootElement(localName = "book") // <2>
+public record Book(@JacksonXmlProperty(isAttribute = false) String name,
+                   @JacksonXmlProperty(isAttribute = true) String isbn) { // <3>
+}

guides/micronaut-produces-xml/java/src/main/java/example/micronaut/BookController.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017-2024 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.micronaut;
+
+import io.micronaut.http.MediaType;
+import io.micronaut.http.annotation.Controller;
+import io.micronaut.http.annotation.Get;
+import io.micronaut.http.annotation.Produces;
+
+@Controller("/book") // <1>
+class BookController {
+
+    @Produces(MediaType.APPLICATION_XML) // <2>
+    @Get // <3>
+    Book index() {
+        return new Book("Building Microservices", "1491950358");
+    }
+}

guides/micronaut-produces-xml/java/src/test/java/example/micronaut/BookControllerTest.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2017-2024 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.micronaut;
+
+import io.micronaut.http.HttpRequest;
+import io.micronaut.http.MediaType;
+import io.micronaut.http.client.BlockingHttpClient;
+import io.micronaut.http.client.HttpClient;
+import io.micronaut.http.client.annotation.Client;
+import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+@MicronautTest // <1>
+class BookControllerTest {
+
+    @Test
+    void testXmlRendered(@Client("/") HttpClient httpClient) { // <2>
+        BlockingHttpClient client = httpClient.toBlocking();
+        String xml = assertDoesNotThrow(() ->
+                client.retrieve(HttpRequest.GET("/book").accept(MediaType.APPLICATION_XML), String.class));  // <3>
+        assertEquals("""
+                <book isbn="1491950358"><name>Building Microservices</name></book>""", xml);
+    }
+}

guides/micronaut-produces-xml/metadata.json

@@ -0,0 +1,15 @@
+{
+  "title": "Render XML in a Micronaut Controller",
+  "base": "hello-base",
+  "intro": "Learn how to use Jackson to render XML in a Micronaut Controller.",
+  "authors": ["Sergio del Amo"],
+  "categories": ["Beyond the Basics"],
+  "publicationDate": "2024-01-15",
+  "languages": ["java"],
+  "apps": [
+    {
+      "name": "default",
+      "features": ["jackson-databind", "jackson-xml"]
+    }
+  ]
+}

guides/micronaut-produces-xml/micronaut-produces-xml.adoc

@@ -0,0 +1,72 @@
+common:header.adoc[]
+
+common:requirements.adoc[]
+
+common:completesolution.adoc[]
+
+common:create-app-features.adoc[]
+
+=== Dependency
+
+In this guide, to render XML, we use https://micronaut-projects.github.io/micronaut-jackson-xml/latest/guide[Micronaut Jackson XML]. Add the following dependency:
+
+dependency:micronaut-jackson-xml[groupId=io.micronaut.xml]
+
+WARNING: https://micronaut-projects.github.io/micronaut-serialization/latest/guide[Micronaut Serialization] doesn't currently support XML
+
+=== Book Record
+
+Create a record for the XML model.
+
+source:Book[]
+callout:introspected[1]
+<2> `@JacksonXmlRootElement` annotation defines the name of root element used for the root-level object when serialized.
+<3> `@JacksonXmlProperty` annotation provides XML-specific configuration for properties.
+
+=== Book Cotroller
+Create a controller which returns a `Book` instance.
+
+source:BookController[]
+
+callout:controller[number=1,arg0=/book]
+callout:produces-xml[2]
+callout:get-generic[3]
+
+== Tests
+Create a test which verifies tha the controller returns XML.
+
+test:BookControllerTest[]
+
+callout:micronaut-test[1]
+callout:http-client[2]
+callout:http-request[3]
+
+common:testApp.adoc[]
+
+common:nativetest.adoc[]
+
+common:graal-with-plugins.adoc[]
+
+:exclude-for-languages:groovy
+
+You can execute the `÷books` endpoint exposed by the native executable:
+
+[source, bash]
+----
+curl localhost:8080/book
+----
+
+[source,xml]
+----
+<book isbn="1491950358"><name>Building Microservices</name></book>
+----
+
+:exclude-for-languages:groovy
+
+common:next.adoc[]
+
+Learn more about https://micronaut-projects.github.io/micronaut-jackson-xml/latest/guide/index.html[Micronaut Jackson XML].
+
+common:helpWithMicronaut.adoc[]
+
+https://micronaut-projects.github.io/micronaut-jackson-xml/latest/guide/index.html

src/docs/common/callouts/callout-produces-xml.adoc

@@ -0,0 +1 @@
+Set the response content-type to `XML` with the `@Produces` annotation.