Merge pull request #27 from sitegeist/mficzel-patch-2

DOCS: Improve README.md

Author: mficzel

README.md

@@ -1,9 +1,24 @@
 # Sitegeist.SchemeOnYou
+## API Documentation that is always complete, accurate and up to date. For humans and machines
 
-Build APIs with autogenerated OpenApi-Specs by using scalar Types, data transfer objects (DTOs) and collections of DTOs.
+SchemOnYou makes the implementation of REST/JSON APIs simple and easy. It enforces strong conventions and
+modern type safe php code for data transfer objects (DTOs). SchemOnYou generates OpenApi-Specs directy 
+from the controller code wich ensures that the documentation is always complete, up to date and accurate.
+
+Since OpenApi-Specs are human and machine readable SchemeOnYou allows to integrate with tools like swagger-ui 
+but also with code generators that allow to generate type safe client code to consume the apis. 
+
+This allows type safe and static analyzable code from the backend through JSON/Rest apis to the frontend and back.
+For faster development pace while maintaining high quality and end to end type safety.
 
 ## TLDR: 
 
+#### Sitegeist.SchemeOnYou provides:
+- A strong convention for PHP DataTransferObjects based on modern PHP code
+- Serializers and deserializers for those DTOs
+- A base class for REST/JSON endpoint controllers where each endpoint recieves and returns DTOs
+- A generator for OpenAPI schemas describing the DTOs and endpoints
+
 #### Differences:
 - Controllers extend `Sitegeist\SchemeOnYou\Application\OpenApiController`
 - ControllerActions must accept and return supported types.