Adds usage examples

Signed-off-by: Tiago Angelo <kurtis.angelo@gmail.com>

Author: angelokurtis

README.md

@@ -1,4 +1,45 @@
 # Go OpenAPI
 
 This project extends the [go-chi](https://github.com/go-chi/chi) router to support OpenAPI 3, bringing to you a simple
-interface to build a router conforming your API contract.
+interface to build a router conforming your API contract.
+
+## Examples
+
+See [_examples/](https://github.com/angelokurtis/go-openapi/blob/main/_examples/) for more examples.
+
+**As easy as:**
+
+```go
+package main
+
+import (
+	_ "embed"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/render"
+
+	"github.com/angelokurtis/go-openapi"
+)
+
+//go:embed openapi.yaml
+var contract []byte
+
+func main() {
+	r := openapi.NewRouter(contract)
+	r.Use(middleware.Logger)
+	r.HandleOperation("getInvites", func(w http.ResponseWriter, r *http.Request) {
+		render.Status(r, http.StatusOK)
+		render.JSON(w, r, map[string]string{"operation": "getInvites"})
+	})
+	r.HandleOperation("createInvite", func(w http.ResponseWriter, r *http.Request) {
+		render.Status(r, http.StatusCreated)
+	})
+	r.HandleOperation("deleteInvite", func(w http.ResponseWriter, r *http.Request) {
+		_ = chi.URLParam(r, "inviteId")
+		render.Status(r, http.StatusNoContent)
+	})
+	http.ListenAndServe(":3000", r)
+}
+```

_examples/guestlist/main.go

@@ -0,0 +1,32 @@
+package main
+
+import (
+	_ "embed"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/render"
+
+	"github.com/angelokurtis/go-openapi"
+)
+
+//go:embed openapi.yaml
+var contract []byte
+
+func main() {
+	r := openapi.NewRouter(contract)
+	r.Use(middleware.Logger)
+	r.HandleOperation("getInvites", func(w http.ResponseWriter, r *http.Request) {
+		render.Status(r, http.StatusOK)
+		render.JSON(w, r, map[string]string{"operation": "getInvites"})
+	})
+	r.HandleOperation("createInvite", func(w http.ResponseWriter, r *http.Request) {
+		render.Status(r, http.StatusCreated)
+	})
+	r.HandleOperation("deleteInvite", func(w http.ResponseWriter, r *http.Request) {
+		_ = chi.URLParam(r, "inviteId")
+		render.Status(r, http.StatusNoContent)
+	})
+	http.ListenAndServe(":3000", r)
+}

_examples/guestlist/openapi.yaml

@@ -0,0 +1,108 @@
+openapi: 3.1.0
+info:
+  title: Guestlist
+  version: 1.0.0
+paths:
+  /invites:
+    summary: Path used to manage the list of invites.
+    description: 'The REST endpoint/path used to list and create zero or more `Invite` entities.  This path contains a `GET` and `POST` operation to perform the list and create tasks, respectively.'
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Invite'
+          description: Successful response - returns an array of `Invite` entities.
+      operationId: getInvites
+      summary: List All Invites
+      description: Gets a list of all `Invite` entities.
+    post:
+      requestBody:
+        description: A new `Invite` to be created.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Invite'
+        required: true
+      responses:
+        '201':
+          description: Successful response.
+      operationId: createInvite
+      summary: Create a Invite
+      description: Creates a new instance of a `Invite`.
+  '/invites/{inviteId}':
+    summary: Path used to manage a single Invite.
+    description: 'The REST endpoint/path used to get, update, and delete single instances of an `Invite`.  This path contains `GET`, `PUT`, and `DELETE` operations used to perform the get, update, and delete tasks, respectively.'
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Invite'
+          description: Successful response - returns a single `Invite`.
+      operationId: getInvite
+      summary: Get a Invite
+      description: Gets the details of a single instance of a `Invite`.
+    put:
+      requestBody:
+        description: Updated `Invite` information.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Invite'
+        required: true
+      responses:
+        '202':
+          description: Successful response.
+      operationId: updateInvite
+      summary: Update a Invite
+      description: Updates an existing `Invite`.
+    delete:
+      responses:
+        '204':
+          description: Successful response.
+      operationId: deleteInvite
+      summary: Delete a Invite
+      description: Deletes an existing `Invite`.
+    parameters:
+      - name: inviteId
+        description: A unique identifier for a `Invite`.
+        schema:
+          type: string
+        in: path
+        required: true
+components:
+  schemas:
+    Invite:
+      title: Root Type for Invite
+      description: ''
+      type: object
+      example:
+        age: 42
+        name: Athena
+        status: CONFIRMED
+      properties:
+        name:
+          type: string
+        age:
+          format: int32
+          type: integer
+        status:
+          type: string
+          enum:
+            - CREATED
+            - ACCEPTED
+            - DECLINED
+            - CONFIRMED
+            - DENIED
+          default: CREATED
+          readOnly: true
+      required:
+        - name
+servers:
+  - description: local
+    url: 'http://localhost:3000'