From e6963f078a1bfb5c018bf3a329e09b3538962e1d Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Mon, 1 Feb 2016 16:09:39 -0800 Subject: [PATCH] schema: regenerate schemas with markdown documentation --- build | 1 + schema/adminschema/README.md | 107 ++++++++++++ schema/adminschema/v1-json.go | 3 +- schema/generator | 12 +- schema/workerschema/README.md | 305 +++++++++++++++++++++++++++++++++ schema/workerschema/v1-gen.go | 3 +- schema/workerschema/v1-json.go | 2 +- 7 files changed, 428 insertions(+), 5 deletions(-) create mode 100644 schema/adminschema/README.md create mode 100644 schema/workerschema/README.md diff --git a/build b/build index eec8fd48..1831bee2 100755 --- a/build +++ b/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 diff --git a/schema/adminschema/README.md b/schema/adminschema/README.md new file mode 100644 index 00000000..cdb7bb89 --- /dev/null +++ b/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 | | + + diff --git a/schema/adminschema/v1-json.go b/schema/adminschema/v1-json.go index 8110bff7..67a8d158 100644 --- a/schema/adminschema/v1-json.go +++ b/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 = `{ } } } -` +` \ No newline at end of file diff --git a/schema/generator b/schema/generator index ffb974c9..54effc73 100755 --- a/schema/generator +++ b/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} diff --git a/schema/workerschema/README.md b/schema/workerschema/README.md new file mode 100644 index 00000000..8ff8c31b --- /dev/null +++ b/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 | | + + diff --git a/schema/workerschema/v1-gen.go b/schema/workerschema/v1-gen.go index 950c9278..7b9aa784 100644 --- a/schema/workerschema/v1-gen.go +++ b/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"` } diff --git a/schema/workerschema/v1-json.go b/schema/workerschema/v1-json.go index 5e6c576d..6c408dc5 100644 --- a/schema/workerschema/v1-json.go +++ b/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." } } },