docs: Improves API docs

client/doc.go

@@ -3,9 +3,9 @@
 // OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are granted
 // to applications that want to use OAuth 2.0 access and refresh tokens.
 //
-//
 // In ORY Hydra, OAuth 2.0 clients are used to manage ORY Hydra itself. These clients may gain highly privileged access
 // if configured that way. This endpoint should be well protected and only called by code you trust.
+//
 // Copyright © 2017 Aeneas Rekkas <[email protected]>
 //
 // Licensed under the Apache License, Version 2.0 (the "License");

client/handler.go

@@ -69,10 +69,9 @@ func (h *Handler) SetRoutes(r *httprouter.Router) {
 //
 // Create an OAuth 2.0 client
 //
-// If you pass `client_secret` the secret will be used, otherwise a random secret will be generated. The secret will
-// be returned in the response and you will not be able to retrieve it later on. Write the secret down and keep
-// it somwhere safe.
+// Create a new OAuth 2.0 client If you pass `client_secret` the secret will be used, otherwise a random secret will be generated. The secret will be returned in the response and you will not be able to retrieve it later on. Write the secret down and keep it somwhere safe.
 //
+// OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are generated for applications which want to consume your OAuth 2.0 or OpenID Connect capabilities. To manage ORY Hydra, you will need an OAuth 2.0 Client as well. Make sure that this endpoint is well protected and only callable by first-party components.
 //
 // The subject making the request needs to be assigned to a policy containing:
 //
@@ -162,9 +161,9 @@ func (h *Handler) Create(w http.ResponseWriter, r *http.Request, _ httprouter.Pa
 //
 // Update an OAuth 2.0 Client
 //
-// If you pass `client_secret` the secret will be updated and returned via the API. This is the only time you will
-// be able to retrieve the client secret, so write it down and keep it safe.
+// Update an existing OAuth 2.0 Client. If you pass `client_secret` the secret will be updated and returned via the API. This is the only time you will be able to retrieve the client secret, so write it down and keep it safe.
 //
+// OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are generated for applications which want to consume your OAuth 2.0 or OpenID Connect capabilities. To manage ORY Hydra, you will need an OAuth 2.0 Client as well. Make sure that this endpoint is well protected and only callable by first-party components.
 //
 // The subject making the request needs to be assigned to a policy containing:
 //
@@ -251,8 +250,9 @@ func (h *Handler) Update(w http.ResponseWriter, r *http.Request, ps httprouter.P
 //
 // List OAuth 2.0 Clients
 //
-// This endpoint never returns passwords.
+// This endpoint lists all clients in the database, and never returns client secrets.
 //
+// OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are generated for applications which want to consume your OAuth 2.0 or OpenID Connect capabilities. To manage ORY Hydra, you will need an OAuth 2.0 Client as well. Make sure that this endpoint is well protected and only callable by first-party components.
 //
 // The subject making the request needs to be assigned to a policy containing:
 //
@@ -311,10 +311,11 @@ func (h *Handler) List(w http.ResponseWriter, r *http.Request, ps httprouter.Par
 
 // swagger:route GET /clients/{id} oAuth2 getOAuth2Client
 //
-// Retrieve an OAuth 2.0 Client.
+// Get an OAuth 2.0 Client.
 //
-// This endpoint never returns passwords.
+// Get an OAUth 2.0 client by its ID. This endpoint never returns passwords.
 //
+// OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are generated for applications which want to consume your OAuth 2.0 or OpenID Connect capabilities. To manage ORY Hydra, you will need an OAuth 2.0 Client as well. Make sure that this endpoint is well protected and only callable by first-party components.
 //
 // The subject making the request needs to be assigned to a policy containing:
 //
@@ -390,6 +391,10 @@ func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Para
 //
 // Deletes an OAuth 2.0 Client
 //
+// Delete an existing OAuth 2.0 Client by its ID.
+//
+// OAuth 2.0 clients are used to perform OAuth 2.0 and OpenID Connect flows. Usually, OAuth 2.0 clients are generated for applications which want to consume your OAuth 2.0 or OpenID Connect capabilities. To manage ORY Hydra, you will need an OAuth 2.0 Client as well. Make sure that this endpoint is well protected and only callable by first-party components.
+//
 // The subject making the request needs to be assigned to a policy containing:
 //
 //  ```

doc.go

@@ -1,14 +1,6 @@
-// Package main Hydra OAuth2 & OpenID Connect Server
+// Package main ORY Hydra - Cloud Native OAuth 2.0 and OpenID Connect Server
 //
-// Hydra offers OAuth 2.0 and OpenID Connect Core 1.0 capabilities as a service. Hydra is different, because it works with any existing authentication infrastructure, not just LDAP or SAML. By implementing a consent app (works with any programming language) you build a bridge between Hydra and your authentication infrastructure.
-// Hydra is able to securely manage JSON Web Keys, and has a sophisticated policy-based access control you can use if you want to.
-// Hydra is suitable for green- (new) and brownfield (existing) projects. If you are not familiar with OAuth 2.0 and are working on a greenfield project, we recommend evaluating if OAuth 2.0 really serves your purpose. Knowledge of OAuth 2.0 is imperative in understanding what Hydra does and how it works.
-//
-// The API documentation always refers to the latest tagged version of ORY Hydra. For previous API documentations, please
-// refer to `https://github.com/ory/hydra/blob/<tag-id>/docs/api.swagger.yaml` - for example:
-//
-// - 0.9.13: https://github.com/ory/hydra/blob/v0.9.13/docs/api.swagger.yaml
-// - 0.8.1: https://github.com/ory/hydra/blob/v0.8.1/docs/api.swagger.yaml
+// Welcome to the ORY Hydra HTTP API documentation. You will find documentation for all HTTP APIs here. Keep in mind that this document reflects the latest branch, always. Support for versioned documentation is coming in the future.
 //
 //     Schemes: http, https
 //     Host: