From 37782e7a553986d0c4111dc423d52fb4f872c437 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Antonio=20Perdiguero?= <perdy@perdy.io>
Date: Tue, 5 Feb 2019 17:09:09 +0100
Subject: [PATCH] Update Starlette API section in third-party docs (#377)

---
 docs/third-party-packages.md | 67 +++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/docs/third-party-packages.md b/docs/third-party-packages.md
index b8bacb74..58a06633 100644
--- a/docs/third-party-packages.md
+++ b/docs/third-party-packages.md
@@ -17,12 +17,71 @@ Document your REST API built with Starlette by declaring OpenAPI (Swagger) schem
 
 Link: <a href="https://github.com/PeRDy/starlette-api" target="_blank">https://github.com/PeRDy/starlette-api</a>
 
-That library aims to bring a layer on top of Starlette framework to provide useful mechanism for building APIs. It's based on API Star, inheriting some nice ideas like:
+That library aims to bring a layer on top of Starlette framework to provide useful mechanism for building APIs. It's 
+based on API Star, inheriting some nice ideas like:
 
-* **Schema system** based on Marshmallow that allows to declare the inputs and outputs of endpoints and provides a reliable way of validate data against those schemas.
+* **Schema system** based on [Marshmallow](https://github.com/marshmallow-code/marshmallow/) that allows to **declare**
+the inputs and outputs of endpoints and provides a reliable way of **validate** data against those schemas.
 * **Dependency Injection** that ease the process of managing parameters needed in endpoints.
-* **Components** as the base of the plugin ecosystem, allowing you to create custom or use those already defined in your endpoints, injected as parameters.
-* **Starlette ASGI** objects like `Request`, `Response`, `Session` and so on are defined as components and ready to be injected in your endpoints.
+* **Components** as the base of the plugin ecosystem, allowing you to create custom or use those already defined in 
+your endpoints, injected as parameters.
+* **Starlette ASGI** objects like `Request`, `Response`, `Session` and so on are defined as components and ready to be 
+injected in your endpoints.
+* **Auto generated API schema** using OpenAPI standard. It uses the schema system of your endpoints to extract all the 
+necessary information to generate your API Schema.
+* **Auto generated docs** providing a [Swagger UI](https://swagger.io/tools/swagger-ui/) or 
+[ReDocs](https://rebilly.github.io/ReDoc/) endpoint.
+
+
+```python
+from marshmallow import Schema, fields, validate
+from starlette_api.applications import Starlette
+
+
+# Data Schema
+class Puppy(Schema):
+    id = fields.Integer()
+    name = fields.String()
+    age = fields.Integer(validate=validate.Range(min=0))
+
+
+# Database
+puppies = [
+    {"id": 1, "name": "Canna", "age": 6},
+    {"id": 2, "name": "Sandy", "age": 12},
+]
+
+
+# Application
+app = Starlette(
+    components=[],      # Without custom components
+    title="Foo",        # API title
+    version="0.1",      # API version
+    description="Bar",  # API description
+    schema="/schema/",  # Path to expose OpenAPI schema
+    docs="/docs/",      # Path to expose Swagger UI docs
+    redoc="/redoc/",    # Path to expose ReDoc docs
+)
+
+
+# Views
+@app.route("/", methods=["GET"])
+def list_puppies(name: str = None) -> Puppy(many=True):
+    """
+    List the puppies collection. There is an optional query parameter that 
+    specifies a name for filtering the collection based on it.
+    
+    Request example:
+    GET http://example.com/?name=Sandy
+    
+    Response example:
+    200
+    [
+        {"id": 2, "name": "Sandy", "age": 12}
+    ]
+    """
+    return [puppy for puppy in puppies if puppy["name"] == name]
+```
 
 ### webargs-starlette