From b725a1253ec8868d7607ce8d63b9d766af22fa61 Mon Sep 17 00:00:00 2001
From: Evert De Spiegeleer <evert.despiegeleer@rightcrowd.com>
Date: Sun, 14 Jan 2024 15:30:08 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20=F0=9F=93=9A=EF=B8=8F=20improve=20readm?=
 =?UTF-8?q?e?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 examples/concept-server.ts |  2 +-
 examples/direct-openapi.ts |  5 +++++
 readme.md                  | 33 ++++++++++++++++++++++++++++++++-
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 examples/direct-openapi.ts

diff --git a/examples/concept-server.ts b/examples/concept-server.ts
index e7ad089..c99639f 100644
--- a/examples/concept-server.ts
+++ b/examples/concept-server.ts
@@ -2,7 +2,7 @@ import { Server } from '@zhttp/core'
 import { greetingController } from './concept-controller.js'
 import { lastVisitMiddleware } from './concept-middleware.js'
 
-const server = new Server({
+export const server = new Server({
   controllers: [greetingController],
   middlewares: [lastVisitMiddleware]
 }, {
diff --git a/examples/direct-openapi.ts b/examples/direct-openapi.ts
new file mode 100644
index 0000000..91d1756
--- /dev/null
+++ b/examples/direct-openapi.ts
@@ -0,0 +1,5 @@
+import { server } from './concept-server.js'
+
+console.log(
+  server.oasInstance.getJsonSpec()
+)
diff --git a/readme.md b/readme.md
index 1fcf36b..f2aa891 100644
--- a/readme.md
+++ b/readme.md
@@ -1,5 +1,9 @@
 ![zhttp, a minimal, typesafe HTTP library with Zod validation](./.readme-assets/header.png)
 
+`zhttp`  is a minimal, typesafe, [OpenAPI](https://www.openapis.org/) compatible HTTP library. It's build around [express](https://github.com/expressjs/express) and [Zod](https://github.com/colinhacks/zod).
+
+`zhttp` solves some of the pains of building an API with express (handler typing, error handling, input/output validation...) while attempting to stay as flexible as possible.
+
 # Installation
 
 ```sh
@@ -75,6 +79,14 @@ server.start()
 
 ## Middleware
 
+A middleware is a function that operates between an incoming request and the corresponding outgoing response. It serves as a processing layer before or after an endpoint handler, carrying out tasks like logging, authentication, and other sorts of data manipulation.
+
+Middlewares in `zhttp` are essentially just express middlewares, with two extra properties: their type ([indicating when to run them](#order-of-execution)), and an optional name.
+Middlewares can be bound on multiple levels:
+- The server
+- A controller
+- An endpoint
+
 ### Basic middleware example
 
 ```ts
@@ -105,6 +117,8 @@ export const lastVisitMiddleware = middleware({
 
 ## Endpoints
 
+<!-- TODO: add docs for endpoints/endpoint handler -->
+
 ### Basic endpoint example
 
 ```ts
@@ -195,7 +209,7 @@ import { Server } from '@zhttp/core'
 import { greetingController } from './concept-controller.js'
 import { lastVisitMiddleware } from './concept-middleware.js'
 
-const server = new Server({
+export const server = new Server({
   controllers: [greetingController],
   middlewares: [lastVisitMiddleware]
 }, {
@@ -209,8 +223,25 @@ server.start()
 
 # OpenAPI
 
+## `openapiController`
+
 The package exports a special controller `openapiController`. When used, this controller exposes routes `/openapi.json` (the OpenAPI json spec) and `/api.html` (a [RapiDoc](https://rapidocweb.com/) api interface).
 
+## Programmatic access
+
+The openapi definition can be directly from the server object.
+
+```ts
+// ./examples/direct-openapi.ts
+
+import { server } from './concept-server.js'
+
+console.log(
+  server.oasInstance.getJsonSpec()
+)
+
+```
+
 # Errors
 
 `zhttp` has a [built in error handler](./packages/core/src/middleware/errorHandler.ts*), which will catch any sort of error thrown in an endpoint or middleware.