chore: format and update swagger titles

ory · Sep 1, 2020 · bf98b54 · bf98b54
1 parent 82d506e
commit bf98b54
Show file tree

Hide file tree

Showing 34 changed files with 594 additions and 747 deletions.
diff --git a/.schema/api.swagger.json b/.schema/api.swagger.json
@@ -318,6 +318,24 @@
         }
       }
     },
+    "/metrics/prometheus": {
+      "get": {
+        "description": "```\nmetadata:\nannotations:\nprometheus.io/port: \"4434\"\nprometheus.io/path: \"/metrics/prometheus\"\n```",
+        "produces": [
+          "plain/text"
+        ],
+        "tags": [
+          "admin"
+        ],
+        "summary": "Get snapshot metrics from the Hydra service. If you're using k8s, you can then add annotations to\nyour deployment like so:",
+        "operationId": "prometheus",
+        "responses": {
+          "200": {
+            "description": "Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is\ntypically 201."
+          }
+        }
+      }
+    },
     "/recovery/link": {
       "post": {
         "description": "This endpoint creates a recovery link which should be given to the user in order for them to recover\n(or activate) their account.",
@@ -375,7 +393,7 @@
     },
     "/schemas/{id}": {
       "get": {
-        "description": "Get a traits schema definition",
+        "description": "Get a Traits Schema Definition",
         "produces": [
           "application/json"
         ],
@@ -459,7 +477,7 @@
         "tags": [
           "public"
         ],
-        "summary": "Complete the browser-based settings flow for the OpenID Connect strategy",
+        "summary": "Complete the Browser-Based Settings Flow for the OpenID Connect Strategy",
         "operationId": "completeSelfServiceBrowserSettingsOIDCSettingsFlow",
         "responses": {
           "302": {
@@ -489,7 +507,7 @@
           "public",
           "admin"
         ],
-        "summary": "Get user-facing self-service errors",
+        "summary": "Get User-Facing Self-Service Errors",
         "operationId": "getSelfServiceError",
         "parameters": [
           {
@@ -610,7 +628,7 @@
           "public",
           "admin"
         ],
-        "summary": "Get information about a login flow",
+        "summary": "Get Login Flow",
         "operationId": "getSelfServiceLoginFlow",
         "parameters": [
           {
@@ -880,12 +898,6 @@
           }
         ],
         "responses": {
-          "200": {
-            "description": "recoveryFlow",
-            "schema": {
-              "$ref": "#/definitions/recoveryFlow"
-            }
-          },
           "302": {
             "description": "Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is\ntypically 201."
           },
@@ -978,7 +990,7 @@
           "public",
           "admin"
         ],
-        "summary": "Get information about a registration flow",
+        "summary": "Get Registration Flow",
         "operationId": "getSelfServiceRegistrationFlow",
         "parameters": [
           {
@@ -1157,7 +1169,7 @@
           "public",
           "admin"
         ],
-        "summary": "Get Information About a Settings Flow",
+        "summary": "Get Settings Flow",
         "operationId": "getSelfServiceSettingsFlow",
         "parameters": [
           {
@@ -1403,7 +1415,7 @@
           "public",
           "admin"
         ],
-        "summary": "Get information about a verification flow",
+        "summary": "Get Verification Flow",
         "operationId": "getSelfServiceVerificationFlow",
         "parameters": [
           {
@@ -1483,12 +1495,6 @@
           }
         ],
         "responses": {
-          "200": {
-            "description": "verificationFlow",
-            "schema": {
-              "$ref": "#/definitions/verificationFlow"
-            }
-          },
           "302": {
             "description": "Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is\ntypically 201."
           },
@@ -1567,7 +1573,7 @@
         "tags": [
           "public"
         ],
-        "summary": "Check who the current HTTP session belongs to",
+        "summary": "Check Who the Current HTTP Session Belongs To",
         "operationId": "whoami",
         "responses": {
           "200": {
@@ -1822,14 +1828,9 @@
         "value",
         "verified",
         "via",
-        "status",
-        "expires_at"
+        "status"
       ],
       "properties": {
-        "expires_at": {
-          "type": "string",
-          "format": "date-time"
-        },
         "id": {
           "$ref": "#/definitions/UUID"
         },

diff --git a/docs/docs/admin/managing-users-identities.mdx b/docs/docs/admin/managing-users-identities.mdx
@@ -74,7 +74,6 @@ To create the account recovery link, use:
   ]}>
 <TabItem value="curl">
 
-
 ```shell script
 $ curl --request POST -sL \
     --header "Content-Type: application/json" \
@@ -94,7 +93,6 @@ $ curl --request POST -sL \
 </TabItem>
 <TabItem value="go">
 
-
 ```go
 package main
 
@@ -145,7 +143,6 @@ email, this feature is tracked as
 </TabItem>
 </Tabs>
 
-
 ### Import a User Identity
 
 This feature is not implemented yet.

diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
@@ -13,13 +13,11 @@ https://github.com/ory/meta/blob/master/templates/repository/CONTRIBUTING.md
 
 -->
 
-
 # Contributing to ORY {{Project}}
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Introduction](#introduction)
 - [Contributing Code](#contributing-code)
 - [Disclosing vulnerabilities](#disclosing-vulnerabilities)
@@ -88,7 +86,8 @@ Please follow these guidelines when formatting source code:
 Please provide documentation when changing, removing, or adding features.
 Documentation resides in the project's `docs` folder.
 
-In cases where a project does not have a `docs` folder check the README for instructions.
+In cases where a project does not have a `docs` folder check the README for
+instructions.
 
 The commands listed below work exclusively for projects with a `docs` folder
 
@@ -110,8 +109,8 @@ To start a local development server with hot reloading, run:
 $ npm start
 ```
 
-This command opens up a browser window. Please note that changes to the sidebar are not hot-reloaded
-and require a restart of the command.
+This command opens up a browser window. Please note that changes to the sidebar
+are not hot-reloaded and require a restart of the command.
 
 #### Build
 
@@ -148,27 +147,32 @@ please include a note in your commit message explaining why.
 
 ## How We Organize Our Work
 
-All repositories in the [ORY organization](https://github.com/ory) have their issues and pull requests 
-monitored in the [ORY Monitoring Board](https://github.com/orgs/ory/projects/9). This allows
-for a transparent backlog of unanswered issues and pull requests across the ecosystem from those
-who are allowed to merge pull requests to the main branch.
+All repositories in the [ORY organization](https://github.com/ory) have their
+issues and pull requests monitored in the
+[ORY Monitoring Board](https://github.com/orgs/ory/projects/9). This allows for
+a transparent backlog of unanswered issues and pull requests across the
+ecosystem from those who are allowed to merge pull requests to the main branch.
 
 The process is as follows:
 
-1. *Cards* represent open issues and pull requests and are automatically assigned to the **Triage** column if
-the author is not one of the maintainers and no maintainer has answered yet.
-2. A maintainer assigns the issue or pull request to someone or adds the label *help wanted*
-which moves the card to **Requires Action**.
-3. If a maintainer leaves a comment or review, the card moves to **Pending Reply**, implying that
-the original author needs to do something (e.g. implement a change, explain something in more detail, ...).
-4. If a non-maintainer pushes changes to the pull request or leaves a comment, the card moves
-back to **Requires Action**.
-5. If a card stays inactive for 60 days or more days, we assume that public interest in the issue
-or change has waned, **archiving** the card.
-6. If the issue is closed or the pull request merged or closed, the card is **archived** as well.
-
-We try our best to answer all issues and review all pull requests and hope that this transparent way
-of keeping a backlog helps you better understand how heavy the workload is.
+1. _Cards_ represent open issues and pull requests and are automatically
+   assigned to the **Triage** column if the author is not one of the maintainers
+   and no maintainer has answered yet.
+2. A maintainer assigns the issue or pull request to someone or adds the label
+   _help wanted_ which moves the card to **Requires Action**.
+3. If a maintainer leaves a comment or review, the card moves to **Pending
+   Reply**, implying that the original author needs to do something (e.g.
+   implement a change, explain something in more detail, ...).
+4. If a non-maintainer pushes changes to the pull request or leaves a comment,
+   the card moves back to **Requires Action**.
+5. If a card stays inactive for 60 days or more days, we assume that public
+   interest in the issue or change has waned, **archiving** the card.
+6. If the issue is closed or the pull request merged or closed, the card is
+   **archived** as well.
+
+We try our best to answer all issues and review all pull requests and hope that
+this transparent way of keeping a backlog helps you better understand how heavy
+the workload is.
 
 ## Communication
 

diff --git a/docs/docs/guides/login-session.mdx b/docs/docs/guides/login-session.mdx
@@ -11,8 +11,8 @@ cookie or as a token, depending on the interaction type.
 
 ## Login Session Configuration
 
-A session is valid for
-the session lifespan you specify in the ORY Kratos config:
+A session is valid for the session lifespan you specify in the ORY Kratos
+config:
 
 ```yaml title="path/to/kratos/config.yml
 session:
@@ -45,14 +45,17 @@ Once the lifespan is reached, the user needs to sign in again.
 
 ### Browser Client
 
-The easiest way to check if a user is signed in is to call the `http(s)://<kratos-public/sessions/whoami` endpoint
-which will return either a 401 Unauthorized or HTTP 200 OK with the session.
+The easiest way to check if a user is signed in is to call the
+`http(s)://<kratos-public/sessions/whoami` endpoint which will return either a
+401 Unauthorized or HTTP 200 OK with the session.
 
 :::note
 
-Make sure to include the ORY Kratos Session Cookie when calling this endpoint. If you are calling this endpoint
-from a proxy or middleware, make sure to forward the cookies sent to the proxy/middleware. If you are
-calling this endpoint as an AJAX call, make sure to include credentials and configure CORS properly.
+Make sure to include the ORY Kratos Session Cookie when calling this endpoint.
+If you are calling this endpoint from a proxy or middleware, make sure to
+forward the cookies sent to the proxy/middleware. If you are calling this
+endpoint as an AJAX call, make sure to include credentials and configure CORS
+properly.
 
 :::
 
@@ -134,8 +137,9 @@ app.get('/', protect, dashboard)
 
 ### API Client
 
-API clients receive and use ORY Kratos Session Tokens which can be checked by calling the `/sessions/whoami` endpoint
-and including the ORY Kratos Session Token as a bearer token in the HTTP Authorization Header:
+API clients receive and use ORY Kratos Session Tokens which can be checked by
+calling the `/sessions/whoami` endpoint and including the ORY Kratos Session
+Token as a bearer token in the HTTP Authorization Header:
 
 ```shell script
 $ sessionToken=oFZzgLpsacUpUy2cvQPtrGa2046WcXCR