schema: regenerate schemas with markdown documentation

build

@@ -15,3 +15,4 @@ go build -o bin/dexctl -ldflags="$LD_FLAGS" github.com/coreos/dex/cmd/dexctl
 go build -o bin/dex-overlord -ldflags="$LD_FLAGS" github.com/coreos/dex/cmd/dex-overlord
 go build -o bin/example-app github.com/coreos/dex/examples/app
 go build -o bin/example-cli github.com/coreos/dex/examples/cli
+go build -o bin/gendoc github.com/coreos/dex/cmd/gendoc

schema/adminschema/README.md

@@ -0,0 +1,107 @@
+
+# Dex Admin API
+
+The Dex Admin API.
+
+__Version:__ v1
+
+## Models
+
+
+### Admin
+
+
+
+```
+{
+    email: string,
+    id: string,
+    password: string
+}
+```
+
+### State
+
+
+
+```
+{
+    AdminUserCreated: boolean
+}
+```
+
+
+## Paths
+
+
+### POST /admin
+
+> __Summary__
+
+> Create Admin
+
+> __Description__
+
+> Create a new admin user.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+|  | body |  | Yes | [Admin](#admin) | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [Admin](#admin) |
+| default | Unexpected error |  |
+
+
+### GET /admin/{id}
+
+> __Summary__
+
+> Get Admin
+
+> __Description__
+
+> Retrieve information about an admin user.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+| id | path |  | Yes | string | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [Admin](#admin) |
+| default | Unexpected error |  |
+
+
+### GET /state
+
+> __Summary__
+
+> Get State
+
+> __Description__
+
+> Get the state of the Dex DB
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [State](#state) |
+| default | Unexpected error |  |
+
+

schema/adminschema/v1-json.go

@@ -1,5 +1,4 @@
 package adminschema
-
 //
 // This file is automatically generated by schema/generator
 //
@@ -105,4 +104,4 @@ const DiscoveryJSON = `{
       }
   }
 }
-`
+`

schema/generator

@@ -11,17 +11,28 @@ if [ $SCHEMA = "worker" ]; then
     IN="schema/workerschema/v1.json"
     OUT="schema/workerschema/v1-json.go"
     GEN="schema/workerschema/v1-gen.go"
+    DOC="schema/workerschema/README.md"
     GOPKG="workerschema"
 elif [ $SCHEMA = 'admin' ]; then
     IN="schema/adminschema/v1.json"
     OUT="schema/adminschema/v1-json.go"
     GEN="schema/adminschema/v1-gen.go"
+    DOC="schema/adminschema/README.md"
     GOPKG="adminschema"
 else
     echo "Usage: generator [worker|admin]"
     exit 1
 fi
 
+GENDOC=bin/gendoc
+
+if [ ! -f $GENDOC ]; then
+    echo "gendoc command line tool not found. please run build script at the top level of this repo"
+    exit 1
+fi
+
+$GENDOC --f $IN --o $DOC
+
 # See schema/generator_import.go for instructions on updating the dependency
 PKG="google.golang.org/api/google-api-go-generator"
 
@@ -52,5 +63,4 @@ GOPATH=${PWD}/gopath ./bin/google-api-go-generator \
     -output "${GEN}"
 
 # Finally, fix the import in the bindings to refer to the vendored google-api package
-sed -i '' -e "s%google.golang.org%github.com/coreos/dex/Godeps/_workspace/src/google.golang.org%" "${GEN}"
 goimports -w ${GEN}

schema/workerschema/README.md

@@ -0,0 +1,305 @@
+
+# Dex API
+
+The Dex REST API
+
+__Version:__ v1
+
+## Models
+
+
+### Client
+
+
+
+```
+{
+    id: string,
+    redirectURIs: [
+        string
+    ]
+}
+```
+
+### ClientPage
+
+
+
+```
+{
+    clients: [
+        Client
+    ],
+    nextPageToken: string
+}
+```
+
+### ClientWithSecret
+
+
+
+```
+{
+    id: string,
+    redirectURIs: [
+        string
+    ],
+    secret: string
+}
+```
+
+### Error
+
+
+
+```
+{
+    error: string,
+    error_description: string
+}
+```
+
+### User
+
+
+
+```
+{
+    admin: boolean,
+    createdAt: string,
+    disabled: boolean,
+    displayName: string,
+    email: string,
+    emailVerified: boolean,
+    id: string
+}
+```
+
+### UserCreateRequest
+
+
+
+```
+{
+    redirectURL: string,
+    user: User
+}
+```
+
+### UserCreateResponse
+
+
+
+```
+{
+    emailSent: boolean,
+    resetPasswordLink: string,
+    user: User
+}
+```
+
+### UserDisableRequest
+
+
+
+```
+{
+    disable: boolean // If true, disable this user, if false, enable them. No error is signaled if the user state doesn't change.
+}
+```
+
+### UserDisableResponse
+
+
+
+```
+{
+    ok: boolean
+}
+```
+
+### UserResponse
+
+
+
+```
+{
+    user: User
+}
+```
+
+### UsersResponse
+
+
+
+```
+{
+    nextPageToken: string,
+    users: [
+        User
+    ]
+}
+```
+
+
+## Paths
+
+
+### GET /clients
+
+> __Summary__
+
+> List Clients
+
+> __Description__
+
+> Retrieve a page of Client objects.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+| nextPageToken | query |  | No | string | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [ClientPage](#clientpage) |
+| default | Unexpected error |  |
+
+
+### POST /clients
+
+> __Summary__
+
+> Create Clients
+
+> __Description__
+
+> Register a new Client.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+|  | body |  | Yes | [Client](#client) | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [ClientWithSecret](#clientwithsecret) |
+| default | Unexpected error |  |
+
+
+### GET /users
+
+> __Summary__
+
+> List Users
+
+> __Description__
+
+> Retrieve a page of User objects.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+| nextPageToken | query |  | No | string | 
+| maxResults | query |  | No | integer | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [UsersResponse](#usersresponse) |
+| default | Unexpected error |  |
+
+
+### POST /users
+
+> __Summary__
+
+> Create Users
+
+> __Description__
+
+> Create a new User.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+|  | body |  | Yes | [UserCreateRequest](#usercreaterequest) | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [UserCreateResponse](#usercreateresponse) |
+| default | Unexpected error |  |
+
+
+### GET /users/{id}
+
+> __Summary__
+
+> Get Users
+
+> __Description__
+
+> Get a single User object by id.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+| id | path |  | Yes | string | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [UserResponse](#userresponse) |
+| default | Unexpected error |  |
+
+
+### POST /users/{id}/disable
+
+> __Summary__
+
+> Disable Users
+
+> __Description__
+
+> Enable or disable a user.
+
+
+> __Parameters__
+
+> |Name|Located in|Description|Required|Type|
+|:-----|:-----|:-----|:-----|:-----|
+| id | path |  | Yes | string | 
+|  | body |  | Yes | [UserDisableRequest](#userdisablerequest) | 
+
+
+> __Responses__
+
+> |Code|Description|Type|
+|:-----|:-----|:-----|
+| 200 |  | [UserDisableResponse](#userdisableresponse) |
+| default | Unexpected error |  |
+
+

schema/workerschema/v1-gen.go

@@ -137,7 +137,8 @@ type UserCreateResponseUser struct {
 }
 
 type UserDisableRequest struct {
-	// Disable: If true, disable this user, if false, enable them
+	// Disable: If true, disable this user, if false, enable them. No error
+	// is signaled if the user state doesn't change.
 	Disable bool `json:"disable,omitempty"`
 }
 

schema/workerschema/v1-json.go

@@ -176,7 +176,7 @@ const DiscoveryJSON = `{
       "properties": {
         "disable": {
           "type": "boolean",
-          "description": "If true, disable this user, if false, enable them"
+          "description": "If true, disable this user, if false, enable them. No error is signaled if the user state doesn't change."
         }
       }
     },