docs: Improve swagger documentation

README.md

@@ -9,11 +9,10 @@
     <a href="https://patreon.com/user?u=4298803">Support us on patreon!</a>
 </h4>
 
-This is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service
+ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service
 uses Hydra to validate access tokens and policies. This service is under **active development** with **regular breaking changes**.
 
-[![CircleCI](https://circleci.com/gh/ory/oathkeeper/tree/master.svg?style=svg)](https://circleci.com/gh/ory/oathkeeper/tree/master)
-[![Coverage Status](https://coveralls.io/repos/github/ory/oathkeeper/badge.svg?branch=master)](https://coveralls.io/github/ory/oathkeeper?branch=master)
+[![CircleCI](https://circleci.com/gh/ory/oathkeeper.svg?style=svg&circle-token=eb458bf636326d41674141b6bbfa475a39c9db1e)](https://circleci.com/gh/ory/oathkeeper)
 
 ## Running
 

doc.go

@@ -1,4 +1,7 @@
-// Package main Oathkeeper
+// Package main ORY Oathkeeper
+//
+// ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service
+// uses Hydra to validate access tokens and policies.
 //
 // Oathkeeper
 //

docs/api.swagger.json

@@ -11,8 +11,8 @@
   ],
   "swagger": "2.0",
   "info": {
-    "description": "Oathkeeper",
-    "title": "Oathkeeper",
+    "description": "ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service\nuses Hydra to validate access tokens and policies.\n\nOathkeeper",
+    "title": "ORY Oathkeeper",
     "contact": {
       "name": "ORY",
       "url": "https://www.ory.am",
@@ -24,7 +24,7 @@
   "paths": {
     "/rules": {
       "get": {
-        "description": "List all rules",
+        "description": "This method returns an array of all rules that are stored in the backend. This is useful if you want to get a full\nview of what rules you have currently in place.",
         "consumes": [
           "application/json"
         ],
@@ -38,6 +38,7 @@
         "tags": [
           "rule"
         ],
+        "summary": "List all rules",
         "operationId": "listRules",
         "responses": {
           "200": {
@@ -97,7 +98,7 @@
     },
     "/rules/{id}": {
       "get": {
-        "description": "Get a rule",
+        "description": "Use this method to retrieve a rule from the storage. If it does not exist you will receive a 404 error.",
         "consumes": [
           "application/json"
         ],
@@ -111,6 +112,7 @@
         "tags": [
           "rule"
         ],
+        "summary": "Retrieve a rule",
         "operationId": "getRule",
         "parameters": [
           {
@@ -140,7 +142,7 @@
         }
       },
       "put": {
-        "description": "Update a rule",
+        "description": "Use this method to update a rule. Keep in mind that you need to send the full rule payload as this endpoint does\nnot support patching.",
         "consumes": [
           "application/json"
         ],
@@ -154,6 +156,7 @@
         "tags": [
           "rule"
         ],
+        "summary": "Update a rule",
         "operationId": "updateRule",
         "parameters": [
           {
@@ -190,7 +193,7 @@
         }
       },
       "delete": {
-        "description": "Delete a rule",
+        "description": "Use this endpoint to delete a rule.",
         "consumes": [
           "application/json"
         ],
@@ -204,6 +207,7 @@
         "tags": [
           "rule"
         ],
+        "summary": "Delete a rule",
         "operationId": "deleteRule",
         "parameters": [
           {
@@ -240,55 +244,55 @@
       "type": "object",
       "properties": {
         "allowAnonymousModeEnabled": {
-          "description": "AllowAnonymousModeEnabled sets if the endpoint is public, thus not needing any authorization at all.",
+          "description": "If set to true, the protected endpoint is available to anonymous users. That means that the endpoint is accessible\nwithout having a valid access token. This setting overrides `basicAuthorizationModeEnabled`.",
           "type": "boolean",
           "x-go-name": "AllowAnonymousModeEnabled"
         },
         "basicAuthorizationModeEnabled": {
-          "description": "BasicAuthorizationModeEnabled if set true disables checking access control policies.",
+          "description": "If set to true, disables checks against ORY Hydra's Warden API and uses basic authorization. This means that\nthe access token is validated (e.g. checking if it is expired, check if it claimed the necessary scopes)\nbut does not use the `requiredAction` and `requiredResource` fields for advanced access control.",
           "type": "boolean",
           "x-go-name": "BasicAuthorizationModeEnabled"
         },
         "description": {
-          "description": "Description describes the rule.",
+          "description": "A human readable description of this rule.",
           "type": "string",
           "x-go-name": "Description"
         },
         "id": {
-          "description": "ID the a unique id of a rule.",
+          "description": "The ID is the unique id of the rule. It can be at most 190 characters long, but the layout of the ID is up to you.\nYou will need this ID later on to update or delete the rule.",
           "type": "string",
           "x-go-name": "ID"
         },
         "matchesMethods": {
-          "description": "MatchesMethods is a list of HTTP methods that this rule matches.",
+          "description": "An array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...). When ORY Oathkeeper searches for rules\nto decide what to do with an incoming request to the proxy server, it compares the HTTP method of the incoming\nrequest with the HTTP methods of each rules. If a match is found, the rule is considered a partial match.\nIf the matchesUrl field is satisfied as well, the rule is considered a full match.",
           "type": "array",
           "items": {
             "type": "string"
           },
           "x-go-name": "MatchesMethods"
         },
         "matchesUrl": {
-          "description": "MatchesURL is a regular expression of paths this rule matches.",
+          "description": "This field represents the URL pattern this rule matches. When ORY Oathkeeper searches for rules\nto decide what to do with an incoming request to the proxy server, it compares the full request URL\n(e.g. https://mydomain.com/api/resource) without query parameters of the incoming\nrequest with this field. If a match is found, the rule is considered a partial match.\nIf the matchesMethods field is satisfied as well, the rule is considered a full match.\n\nYou can use regular expressions in this field to match more than one url. Regular expressions are encapsulated in\nbrackets \u003c and \u003e. The following example matches all paths of the domain `mydomain.com`: `https://mydomain.com/\u003c.*\u003e`.\n\nFor more information refer to: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules",
           "type": "string",
           "x-go-name": "MatchesURL"
         },
         "passThroughModeEnabled": {
-          "description": "PassThroughModeEnabled if set true disables firewall capabilities.",
+          "description": "If set to true, any authorization logic is completely disabled and the Authorization header is not changed at all.\nThis is useful if you have an endpoint that has it's own authorization logic, for example using basic authorization.\nIf set to true, this setting overrides `basicAuthorizationModeEnabled` and `allowAnonymousModeEnabled`.",
           "type": "boolean",
           "x-go-name": "PassThroughModeEnabled"
         },
         "requiredAction": {
-          "description": "RequiredScopes is the action this rule requires.",
+          "description": "This field will be used to decide advanced authorization requests where access control policies are used. A\naction is typically something a user wants to do (e.g. write, read, delete).\nThis field supports expansion as described in the developer guide: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules",
           "type": "string",
           "x-go-name": "RequiredAction"
         },
         "requiredResource": {
-          "description": "RequiredScopes is the resource this rule requires.",
+          "description": "This field will be used to decide advanced authorization requests where access control policies are used. A\nresource is typically something a user wants to access (e.g. printer, article, virtual machine).\nThis field supports expansion as described in the developer guide: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules",
           "type": "string",
           "x-go-name": "RequiredResource"
         },
         "requiredScopes": {
-          "description": "RequiredScopes is a list of scopes that are required by this rule.",
+          "description": "An array of OAuth 2.0 scopes that are required when accessing an endpoint protected by this rule.\nIf the token used in the Authorization header did not request that specific scope, the request is denied.",
           "type": "array",
           "items": {
             "type": "string"

rule/doc.go

@@ -1,6 +1,11 @@
-// package rule encapsulates rule management logic as well as rule matching logic.
+// Package rule implements management capabilities for rules
 //
+// A rule is used to decide what to do with requests that are hitting the ORY Oathkeeper proxy server. A rule must
+// define the HTTP methods and the URL under which it will apply. A URL may not have more than one rule. If a URL
+// has no rule applied, the proxy server will return a 404 not found error.
 //
+// ORY Oathkeeper stores as many rules as required and iterates through them on every request. Rules are essential
+// to the way ORY Oathkeeper works. To read more on rules, please refer to the developer guide: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules
 package rule
 
 // A rule
@@ -44,33 +49,56 @@ type swaggerCreateRuleParameters struct {
 // A rule
 // swagger:model rule
 type jsonRule struct {
-	// ID the a unique id of a rule.
+	// The ID is the unique id of the rule. It can be at most 190 characters long, but the layout of the ID is up to you.
+	// You will need this ID later on to update or delete the rule.
 	ID string `json:"id" db:"id"`
 
-	// MatchesMethods is a list of HTTP methods that this rule matches.
+	// A human readable description of this rule.
+	Description string `json:"description"`
+
+	// An array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...). When ORY Oathkeeper searches for rules
+	// to decide what to do with an incoming request to the proxy server, it compares the HTTP method of the incoming
+	// request with the HTTP methods of each rules. If a match is found, the rule is considered a partial match.
+	// If the matchesUrl field is satisfied as well, the rule is considered a full match.
 	MatchesMethods []string `json:"matchesMethods"`
 
-	// MatchesURL is a regular expression of paths this rule matches.
+	// This field represents the URL pattern this rule matches. When ORY Oathkeeper searches for rules
+	// to decide what to do with an incoming request to the proxy server, it compares the full request URL
+	// (e.g. https://mydomain.com/api/resource) without query parameters of the incoming
+	// request with this field. If a match is found, the rule is considered a partial match.
+	// If the matchesMethods field is satisfied as well, the rule is considered a full match.
+	//
+	// You can use regular expressions in this field to match more than one url. Regular expressions are encapsulated in
+	// brackets < and >. The following example matches all paths of the domain `mydomain.com`: `https://mydomain.com/<.*>`.
+	//
+	// For more information refer to: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules
 	MatchesURL string `json:"matchesUrl"`
 
-	// RequiredScopes is a list of scopes that are required by this rule.
+	// An array of OAuth 2.0 scopes that are required when accessing an endpoint protected by this rule.
+	// If the token used in the Authorization header did not request that specific scope, the request is denied.
 	RequiredScopes []string `json:"requiredScopes"`
 
-	// RequiredScopes is the action this rule requires.
-	RequiredAction string `json:"requiredAction"`
-
-	// RequiredScopes is the resource this rule requires.
-	RequiredResource string `json:"requiredResource"`
+	// If set to true, any authorization logic is completely disabled and the Authorization header is not changed at all.
+	// This is useful if you have an endpoint that has it's own authorization logic, for example using basic authorization.
+	// If set to true, this setting overrides `basicAuthorizationModeEnabled` and `allowAnonymousModeEnabled`.
+	PassThroughModeEnabled bool `json:"passThroughModeEnabled"`
 
-	// AllowAnonymousModeEnabled sets if the endpoint is public, thus not needing any authorization at all.
+	// If set to true, the protected endpoint is available to anonymous users. That means that the endpoint is accessible
+	// without having a valid access token. This setting overrides `basicAuthorizationModeEnabled`.
 	AllowAnonymousModeEnabled bool `json:"allowAnonymousModeEnabled"`
 
-	// Description describes the rule.
-	Description string `json:"description"`
+	// If set to true, disables checks against ORY Hydra's Warden API and uses basic authorization. This means that
+	// the access token is validated (e.g. checking if it is expired, check if it claimed the necessary scopes)
+	// but does not use the `requiredAction` and `requiredResource` fields for advanced access control.
+	BasicAuthorizationModeEnabled bool `json:"basicAuthorizationModeEnabled"`
 
-	// PassThroughModeEnabled if set true disables firewall capabilities.
-	PassThroughModeEnabled bool `json:"passThroughModeEnabled"`
+	// This field will be used to decide advanced authorization requests where access control policies are used. A
+	// action is typically something a user wants to do (e.g. write, read, delete).
+	// This field supports expansion as described in the developer guide: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules
+	RequiredAction string `json:"requiredAction"`
 
-	// BasicAuthorizationModeEnabled if set true disables checking access control policies.
-	BasicAuthorizationModeEnabled bool `json:"basicAuthorizationModeEnabled"`
+	// This field will be used to decide advanced authorization requests where access control policies are used. A
+	// resource is typically something a user wants to access (e.g. printer, article, virtual machine).
+	// This field supports expansion as described in the developer guide: https://ory.gitbooks.io/oathkeeper/content/concepts.html#rules
+	RequiredResource string `json:"requiredResource"`
 }

rule/handler.go

@@ -65,6 +65,9 @@ func (h *Handler) Create(w http.ResponseWriter, r *http.Request, _ httprouter.Pa
 //
 // List all rules
 //
+// This method returns an array of all rules that are stored in the backend. This is useful if you want to get a full
+// view of what rules you have currently in place.
+//
 //     Consumes:
 //     - application/json
 //
@@ -95,7 +98,9 @@ func (h *Handler) List(w http.ResponseWriter, r *http.Request, _ httprouter.Para
 
 // swagger:route GET /rules/{id} rule getRule
 //
-// Get a rule
+// Retrieve a rule
+//
+// Use this method to retrieve a rule from the storage. If it does not exist you will receive a 404 error.
 //
 //     Consumes:
 //     - application/json
@@ -128,6 +133,9 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para
 //
 // Update a rule
 //
+// Use this method to update a rule. Keep in mind that you need to send the full rule payload as this endpoint does
+// not support patching.
+//
 //     Consumes:
 //     - application/json
 //
@@ -162,6 +170,8 @@ func (h *Handler) Update(w http.ResponseWriter, r *http.Request, ps httprouter.P
 //
 // Delete a rule
 //
+// Use this endpoint to delete a rule.
+//
 //     Consumes:
 //     - application/json
 //

rule/rule.go

@@ -10,10 +10,13 @@ import (
 
 // Rule is a single rule that will get checked on every HTTP request.
 type Rule struct {
-	// ID the a unique id of a rule.
+	// ID is the unique id of the rule. It can be at most 190 characters long, but the layout of the ID is up to you.
+	// You will need this ID later on to update or delete the rule.
 	ID string
 
-	// MatchesMethods is a list of HTTP methods that this rule matches.
+	// MatchesMethods as an array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...). When ORY Oathkeeper searches for rules
+	// to decide what to do with an incoming request to the proxy server, it compares the HTTP method of the incoming
+	// request with the HTTP methods of each rules. If a match is found, the rule is considered a partial match.
 	MatchesMethods []string
 
 	// MatchesURLCompiled is a regular expression of paths this rule matches.

sdk/go/oathkeepersdk/swagger/README.md

@@ -1,6 +1,6 @@
 # Go API client for swagger
 
-Oathkeeper
+ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service uses Hydra to validate access tokens and policies.  Oathkeeper
 
 ## Overview
 This API client was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project.  By using the [swagger-spec](https://github.com/swagger-api/swagger-spec) from a remote server, you can easily generate an API client.
@@ -23,10 +23,10 @@ All URIs are relative to *http://localhost*
 Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------
 *RuleApi* | [**CreateRule**](docs/RuleApi.md#createrule) | **Post** /rules | 
-*RuleApi* | [**DeleteRule**](docs/RuleApi.md#deleterule) | **Delete** /rules/{id} | 
-*RuleApi* | [**GetRule**](docs/RuleApi.md#getrule) | **Get** /rules/{id} | 
-*RuleApi* | [**ListRules**](docs/RuleApi.md#listrules) | **Get** /rules | 
-*RuleApi* | [**UpdateRule**](docs/RuleApi.md#updaterule) | **Put** /rules/{id} | 
+*RuleApi* | [**DeleteRule**](docs/RuleApi.md#deleterule) | **Delete** /rules/{id} | Delete a rule
+*RuleApi* | [**GetRule**](docs/RuleApi.md#getrule) | **Get** /rules/{id} | Retrieve a rule
+*RuleApi* | [**ListRules**](docs/RuleApi.md#listrules) | **Get** /rules | List all rules
+*RuleApi* | [**UpdateRule**](docs/RuleApi.md#updaterule) | **Put** /rules/{id} | Update a rule
 
 
 ## Documentation For Models

sdk/go/oathkeepersdk/swagger/api_client.go

@@ -1,7 +1,7 @@
 /*
- * Oathkeeper
+ * ORY Oathkeeper
  *
- * Oathkeeper
+ * ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service uses Hydra to validate access tokens and policies.  Oathkeeper
  *
  * OpenAPI spec version: Latest
  * Contact: [email protected]

sdk/go/oathkeepersdk/swagger/api_response.go

@@ -1,7 +1,7 @@
 /*
- * Oathkeeper
+ * ORY Oathkeeper
  *
- * Oathkeeper
+ * ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service uses Hydra to validate access tokens and policies.  Oathkeeper
  *
  * OpenAPI spec version: Latest
  * Contact: [email protected]

sdk/go/oathkeepersdk/swagger/configuration.go

@@ -1,7 +1,7 @@
 /*
- * Oathkeeper
+ * ORY Oathkeeper
  *
- * Oathkeeper
+ * ORY Oathkeeper is a reverse proxy that checks the HTTP Authorization for validity against a set of rules. This service uses Hydra to validate access tokens and policies.  Oathkeeper
  *
  * OpenAPI spec version: Latest
  * Contact: [email protected]