From f65961c41df7cc2a2a6f6b12925b41aa893c021f Mon Sep 17 00:00:00 2001 From: Martijn Hoekstra Date: Tue, 23 Aug 2022 10:22:23 +0200 Subject: [PATCH] add bare-bones documentation on encoding of bodies --- modules/microsite/docs/scala/akka-http/dtos.md | 10 ++++++++++ modules/microsite/docs/scala/akka-http/index.md | 1 + modules/microsite/docs/scala/http4s/dtos.md | 10 ++++++++++ modules/microsite/docs/scala/http4s/index.md | 11 ++++++----- 4 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 modules/microsite/docs/scala/akka-http/dtos.md create mode 100644 modules/microsite/docs/scala/http4s/dtos.md diff --git a/modules/microsite/docs/scala/akka-http/dtos.md b/modules/microsite/docs/scala/akka-http/dtos.md new file mode 100644 index 0000000000..abb9646780 --- /dev/null +++ b/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. diff --git a/modules/microsite/docs/scala/akka-http/index.md b/modules/microsite/docs/scala/akka-http/index.md index 5d2c6e9808..2ce8bf4263 100644 --- a/modules/microsite/docs/scala/akka-http/index.md +++ b/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) diff --git a/modules/microsite/docs/scala/http4s/dtos.md b/modules/microsite/docs/scala/http4s/dtos.md new file mode 100644 index 0000000000..da5cd4ffd6 --- /dev/null +++ b/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. diff --git a/modules/microsite/docs/scala/http4s/index.md b/modules/microsite/docs/scala/http4s/index.md index 073aad1258..53d946dbf5 100644 --- a/modules/microsite/docs/scala/http4s/index.md +++ b/modules/microsite/docs/scala/http4s/index.md @@ -6,12 +6,13 @@ 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) @@ -19,4 +20,4 @@ Table of Contents 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) \ No newline at end of file +1. [guardrail Extensions](guardrail-extensions)