feat: Add TLDR at the beginning of every articles

alexandre-touret · Dec 15, 2023 · d35a933 · d35a933
1 parent e65bfb8
commit d35a933
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 1 deletion.
diff --git a/docs/01-without_versioning.md b/docs/01-without_versioning.md
@@ -2,6 +2,13 @@
 
 At this point we have our first customer : **John Doe** who uses our API with the current specification.
 
+## TL;DR: What will you learn in this chapter?
+
+This chapter covers the following topics:
+
+1. How to start the platform
+2. Adding a non-breaking change and see how it doesn't impact the API Contract 
+
 ## Prerequisites
 
 You must start three new shells and run [rest-book](../rest-book), [rest-number](../rest-number) and [the gateway](../gateway) modules.

diff --git a/docs/02-first_version.md b/docs/02-first_version.md
@@ -1,5 +1,15 @@
 # Your first version
 
+## TL;DR: What will you learn in this chapter?
+
+This chapter covers the following topics:
+
+1. Pinpoint the impacts of the versioning in the OPENAPI Description file
+2. Implement a URL Based versioning
+3. Implement a header based versioning
+4. Deploy and configure a default version for your API
+
+## Prerequisites
 We will define in this chapter our first version in the URI and in a header mixing in the gateway & the apps.
 
 > **Warning**

diff --git a/docs/03-second_version.md b/docs/03-second_version.md
@@ -1,5 +1,12 @@
 # And now something completely different : a second version
 
+## TL;DR: What are you going to learn in this chapter?
+
+This chapter covers the following topics:
+
+1. Creating a new version (it will be a copy of the rest-book module)
+2. Add a new breaking change functionality to the last version
+
 ## A new functionality for a new customer
 
 We have now a new customer. 

diff --git a/docs/04-scm.md b/docs/04-scm.md
@@ -1,5 +1,12 @@
 # Configuration management
 
+## TL;DR: What are you going to learn in this chapter?
+
+This chapter covers the following topics:
+
+1. Pinpoint Configuration management issues due to API Versioning 
+2. Exposing the two versions on the API Gateway
+
 ## Preamble
 You can configure your services either during deployment using CI tooling, such as [Gitlab Environments](https://docs.gitlab.com/ee/ci/environments/), or any other [Infra As Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) tool ([Istio](https://istio.io/), [Ansible](https://www.ansible.com/),...) or using a configuration server.
 For this workshop, all the configuration items will be provided by [Spring Cloud Config](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_quick_start).

diff --git a/docs/05-conflicts.md b/docs/05-conflicts.md
@@ -1,5 +1,11 @@
 # Dealing with breaking changes
 
+## TL;DR: What are you going to learn in this chapter?
+
+This chapter covers the following topics:
+
+1. Dig into Backward compatibility hassle and implement a solution to make both of the two versions work
+
 ## Preamble
 
 Now it is time to move on.
@@ -370,7 +376,7 @@ http :8083/v2/books
 
 ```
 
-## Striving with changes for existing customers in the v1
+## Striving for changes for existing customers in the v1
 
 Now, the database is not usable as is for the V1.
 

diff --git a/docs/06-authorization.md b/docs/06-authorization.md
@@ -1,5 +1,12 @@
 # Last but not least : what about security and authorization impacts?
 
+## TL;DR: What are you going to learn in this chapter?
+
+This chapter covers the following topics:
+
+1. Pinpointing the impacts on authorization
+2. Enforcing API versions restrictions with OAUTHv2 scopes
+
 While versioning secured APIs, there is usually one impact we miss at the beginning: security, especially authorization.
 If you apply authorization policies on your whole platform using for instance, [ABAC](https://en.wikipedia.org/wiki/Attribute-based_access_control) or [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) approaches, you must take care about it.
 They could indeed evolve over your versions.