Basic docs (#6)

README.md

@@ -4,15 +4,17 @@
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 [![renovate-app badge](https://img.shields.io/badge/renovate-app-blue.svg)](https://renovateapp.com/)
 
-The best way to create REST APIs (is GraphQL)
+The best way to create REST APIs (is GraphQL).
 
 ## Installation
 
     yarn add sofa-api
     # or
     npm install sofa-api
 
-## Example
+## Getting Started
+
+The most basic example possible:
 
 ```ts
 import sofa from 'sofa-api';
@@ -26,6 +28,143 @@ app.use(
     schema,
   })
 );
+
+// GET /api/users
+// GET /api/messages
+```
+
+## How it works
+
+Sofa takes your GraphQL Schema, looks for available queries, mutations and subscriptions and turns all of that into REST API.
+
+Given the following schema:
+
+```graphql
+type User {
+  id: ID
+  name: String
+}
+
+type Query {
+  chat(id: ID): Chat
+  chats: [Chat]
+  me: Chat
+}
+```
+
+Routes that are being generated:
+
+```
+GET /chat/:id
+GET /chats
+GET /me
+```
+
+### Nested data and idea behind Models
+
+Sofa treats some types differently than others, those are called Models.
+
+The idea behind Models is to not expose full objects in every response, especially if it's a nested, not first-level data.
+
+For example, when fetching a list of chats you don't want to include all messages in the response, you want them to be just IDs (or links). Those messages would have to have their own endpoint. We call this type of data, a Model. In REST you probably call them Resources.
+
+In order to treat particular types as Models you need to provide two queries, one that exposes a list and the other to fetch a single entity. The model itself has to have an `id` field. Those are the only requirements.
+
+```graphql
+# Message is treated as a Model
+type Query {
+  messages: [Message]
+  message(id: ID): Message
+}
+
+type Message {
+  id: ID
+  # other fields ...
+}
+```
+
+### Provide a Context
+
+In order for Sofa to resolve operations based on a Context, you need te be able to provide some. Here's how you do it:
+
+```ts
+api.use(
+  '/api',
+  sofa({
+    schema,
+    async context({ req }) {
+      return {
+        req,
+        ...yourContext,
+      };
+    },
+  })
+);
+```
+
+> You can pass a plain object or a function.
+
+### Use full responses instead of IDs
+
+There are some cases where sending a full object makes more sense than passing only the ID. Sofa allows you to easily define where to ignore the default behavior:
+
+```ts
+api.use(
+  '/api',
+  sofa({
+    schema,
+    ignore: ['Message.author'],
+  })
+);
+```
+
+Whenever Sofa tries to resolve an author of a message, instead of exposing an ID it will pass whole data.
+
+> Pattern is easy: `Type:field` or `Type`
+
+### Custom execute phase
+
+By default, Sofa uses `graphql` function from `graphql-js` to turn an operation into data but it's very straightforward to pass your own logic. Thanks to that you can even use a remote GraphQL Server (with Fetch or through Apollo Links).
+
+```ts
+api.use(
+  '/api',
+  sofa({
+    schema,
+    async execute(args) {
+      return yourOwnLogicHere(args);
+    },
+  })
+);
+```
+
+### OpenAPI and Swagger
+
+Thanks to GraphQL's Type System Sofa is able to generate OpenAPI (Swagger) definitions out of it. Possibilities are endless here. You get all the information you need in order to write your own definitions or create a plugin that follows any specification.
+
+```ts
+import sofa, { OpenAPI } from 'sofa-api';
+
+const openApi = OpenAPI({
+  schema,
+  info: {
+    title: 'Example API',
+    version: '3.0.0',
+  },
+});
+
+app.use(
+  '/api',
+  sofa({
+    schema,
+    onRoute(info) {
+      openApi.addRoute(info);
+    },
+  })
+);
+
+// writes every recorder route
+openApi.save('./swagger.yml');
 ```
 
 ## License

package.json

@@ -6,6 +6,29 @@
   "typings": "dest/index.d.ts",
   "sideEffects": false,
   "license": "MIT",
+  "keywords": [
+    "api",
+    "rest",
+    "graphql",
+    "sofa"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "Urigo/sofa"
+  },
+  "author": {
+    "name": "Uri Goldshtein",
+    "email": "[email protected]",
+    "url": "https://github.com/Urigo"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0",
+    "graphql": "^0.13.2 || ^14.0.0"
+  },
+  "dependencies": {
+    "change-case": "3.0.2",
+    "yamljs": "0.3.0"
+  },
   "scripts": {
     "start": "ts-node example/index.ts",
     "prod": "webpack && node dist/bundle.js",
@@ -41,14 +64,6 @@
     "webpack": "4.27.1",
     "webpack-cli": "3.1.2"
   },
-  "dependencies": {
-    "change-case": "3.0.2",
-    "yamljs": "0.3.0"
-  },
-  "peerDependencies": {
-    "express": "^4.0.0",
-    "graphql": "^14.0.0"
-  },
   "husky": {
     "hooks": {
       "pre-commit": "lint-staged"