Merge pull request #1566 from martijnhoekstra/doc/encoding

add bare-bones documentation on encoding of bodies

modules/microsite/docs/scala/akka-http/dtos.md

@@ -0,0 +1,10 @@
+---
+layout: docs
+title: "Encoding - akka-http - scala - guardrail"
+---
+
+guardrail will generate data transfer objects with encoders and decoders for entity bodies of requests and responses, as long as they're specified by a `$ref` reference to either in a components section or in a separate file.
+
+Data transfer objects will be represented as case classes, while encoders and decoders depend on the framework used. For dropwizard for example, guardrail will generate jackson encoders and decoders, while for http4s, guardrail will create encoders and decoders for circe.
+
+When your schemas are defined inline however, guardrail will not build typed DTOs for the schemas, but fall back to a generic json representation. One scenario where this can happen is when your api specification is built as a bundle with swagger-cli. Fortunately, guardrail understands the unbundled representation with ref elements to separate files.

modules/microsite/docs/scala/akka-http/index.md

@@ -12,6 +12,7 @@ Table of Contents
    1. [Fewer binary dependencies](what-is-guardrail#fewer-binary-dependencies)
 1. [Installation](installation)
 1. [Sample API specification](sample-api-specification)
+1. [Generating Domain Objects](dtos)
 1. [Generating a Server](generating-a-server)
    1. [Separation of business logic](generating-a-server#separation-of-business-logic)
    1. [API structure slip is impossible](generating-a-server#api-structure-slip-is-impossible)

modules/microsite/docs/scala/http4s/dtos.md

@@ -0,0 +1,10 @@
+---
+layout: docs
+title: "Encoding - http4s - scala - guardrail"
+---
+
+guardrail will generate data transfer objects with encoders and decoders for entity bodies of requests and responses, as long as they're specified by a `$ref` reference to either in a components section or in a separate file.
+
+Data transfer objects will be represented as case classes, while encoders and decoders depend on the framework used. For dropwizard for example, guardrail will generate jackson encoders and decoders, while for http4s, guardrail will create encoders and decoders for circe.
+
+When your schemas are defined inline however, guardrail will not build typed DTOs for the schemas, but fall back to a generic json representation. One scenario where this can happen is when your api specification is built as a bundle with swagger-cli. Fortunately, guardrail understands the unbundled representation with ref elements to separate files.

modules/microsite/docs/scala/http4s/index.md

@@ -6,17 +6,18 @@ title: "http4s - scala - guardrail"
 Table of Contents
 =================
 
-1. [What is guardrail](what-is-guardrail.md)
-    1. [Single Point of Truth](what-is-guardrail.md#single-point-of-truth)
-    1. [Unexpected API changes are compiler errors](what-is-guardrail.md#unexpected-api-changes-are-compiler-errors)
-    1. [Fewer binary dependencies](what-is-guardrail.md#fewer-binary-dependencies)
+1. [What is guardrail](what-is-guardrail)
+    1. [Single Point of Truth](what-is-guardrail#single-point-of-truth)
+    1. [Unexpected API changes are compiler errors](what-is-guardrail#unexpected-api-changes-are-compiler-errors)
+    1. [Fewer binary dependencies](what-is-guardrail#fewer-binary-dependencies)
 1. [Installation](installation)
 1. [Sample API specification](sample-api-specification)
+1. [Generating Domain Objects](dtos)
 1. [Generating a Server](generating-a-server)
     1. [Separation of business logic](generating-a-server#separation-of-business-logic)
     1. [API structure slip is impossible](generating-a-server#api-structure-slip-is-impossible)
     1. [Generating test-only (real) server mocks for unit tests](generating-a-server#generating-test-only-real-server-mocks-for-unit-tests)
     1. [A note about scalatest integration](generating-a-server#a-note-about-scalatest-integration)
 1. [Generating clients](generating-clients)
     1. [Separation of protocol-concerns from API-level concerns](generating-clients#separation-of-protocol-concerns-from-api-level-concerns)
-1. [guardrail Extensions](guardrail-extensions)
+1. [guardrail Extensions](guardrail-extensions)