fix(sdk): improved OpenAPI specifications for UI nodes (#2375)

Closes #2357 Co-authored-by: zepatrik <zepatrik@users.noreply.github.com>
ory · Apr 16, 2022 · a42a0f7 · a42a0f7
1 parent 8f29d45
commit a42a0f7
Show file tree

Hide file tree

Showing 67 changed files with 449 additions and 277 deletions.
diff --git a/.schema/openapi/patches/schema.yaml b/.schema/openapi/patches/schema.yaml
@@ -8,8 +8,8 @@
     mapping:
       input: "#/components/schemas/uiNodeInputAttributes"
       text: "#/components/schemas/uiNodeTextAttributes"
-      image: "#/components/schemas/uiNodeImageAttributes"
-      anchor: "#/components/schemas/uiNodeAnchorAttributes"
+      img: "#/components/schemas/uiNodeImageAttributes"
+      a: "#/components/schemas/uiNodeAnchorAttributes"
       script: "#/components/schemas/uiNodeScriptAttributes"
 - op: add
   path: /components/schemas/uiNodeAttributes/oneOf

diff --git a/Makefile b/Makefile
@@ -39,6 +39,14 @@ $(call make-lint-dependency)
 docs/cli:
 		go run ./cmd/clidoc/. .
 
+.PHONY: docs/api
+docs/api:
+		npx @redocly/openapi-cli preview-docs spec/api.json
+
+.PHONY: docs/swagger
+docs/swagger:
+		npx @redocly/openapi-cli preview-docs spec/swagger.json
+
 .bin/ory: Makefile
 		bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -d -b .bin ory v0.1.14
 		touch -a -m .bin/ory

diff --git a/README.md b/README.md
@@ -578,3 +578,12 @@ To prepare documentation tests, run `npm i` to install
 
 - test all documentation: <code type="make/command">make test-docs</code>
 - test an individual file: <code type="npm/installed-executable">text-run</code>
+
+#### Preview API documentation
+
+- update the SDK including the OpenAPI specification:
+  <code type="make/command">make sdk</code>
+- run preview server for API documentation: <code type="make/command">make
+  docs/api</code>
+- run preview server for swagger documentation: <code type="make/command">make
+  docs/swagger</code>
diff --git a/internal/httpclient/api/openapi.yaml b/internal/httpclient/api/openapi.yaml
@@ -3461,8 +3461,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           - meta:
               label:
                 context: '{}'
@@ -3478,8 +3478,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           method: method
           action: action
           messages:
@@ -3593,8 +3593,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           - meta:
               label:
                 context: '{}'
@@ -3610,8 +3610,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           method: method
           action: action
           messages:
@@ -3670,6 +3670,7 @@ components:
       - issued_at
       - request_url
       - state
+      - type
       - ui
       title: A Recovery Flow
       type: object
@@ -3727,8 +3728,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           - meta:
               label:
                 context: '{}'
@@ -3744,8 +3745,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           method: method
           action: action
           messages:
@@ -3797,6 +3798,7 @@ components:
       - id
       - issued_at
       - request_url
+      - type
       - ui
       type: object
     selfServiceSettingsFlow:
@@ -3824,8 +3826,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           - meta:
               label:
                 context: '{}'
@@ -3841,8 +3843,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           method: method
           action: action
           messages:
@@ -3949,6 +3951,7 @@ components:
       - issued_at
       - request_url
       - state
+      - type
       - ui
       title: Flow represents a Settings Flow
       type: object
@@ -3988,8 +3991,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           - meta:
               label:
                 context: '{}'
@@ -4005,8 +4008,8 @@ components:
               id: 0
               text: text
               type: type
-            type: type
-            group: group
+            type: text
+            group: default
           method: method
           action: action
           messages:
@@ -4964,8 +4967,8 @@ components:
             id: 0
             text: text
             type: type
-          type: type
-          group: group
+          type: text
+          group: default
         - meta:
             label:
               context: '{}'
@@ -4981,8 +4984,8 @@ components:
             id: 0
             text: text
             type: type
-          type: type
-          group: group
+          type: text
+          group: default
         method: method
         action: action
         messages:
@@ -5035,12 +5038,23 @@ components:
           id: 0
           text: text
           type: type
-        type: type
-        group: group
+        type: text
+        group: default
       properties:
         attributes:
           $ref: '#/components/schemas/uiNodeAttributes'
         group:
+          description: Group specifies which group (e.g. password authenticator) this
+            node belongs to.
+          enum:
+          - default
+          - password
+          - oidc
+          - profile
+          - link
+          - totp
+          - lookup_secret
+          - webauthn
           type: string
         messages:
           items:
@@ -5049,6 +5063,13 @@ components:
         meta:
           $ref: '#/components/schemas/uiNodeMeta'
         type:
+          description: The node's type
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
       required:
       - attributes
@@ -5070,6 +5091,15 @@ components:
           description: A unique identifier
           type: string
         node_type:
+          description: |-
+            NodeType represents this node's types. It is a mirror of `node.type` and
+            is primarily used to allow compatibility with OpenAPI 3.0.
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
         title:
           $ref: '#/components/schemas/uiText'
@@ -5083,8 +5113,8 @@ components:
     uiNodeAttributes:
       discriminator:
         mapping:
-          anchor: '#/components/schemas/uiNodeAnchorAttributes'
-          image: '#/components/schemas/uiNodeImageAttributes'
+          a: '#/components/schemas/uiNodeAnchorAttributes'
+          img: '#/components/schemas/uiNodeImageAttributes'
           input: '#/components/schemas/uiNodeInputAttributes'
           script: '#/components/schemas/uiNodeScriptAttributes'
           text: '#/components/schemas/uiNodeTextAttributes'
@@ -5096,8 +5126,6 @@ components:
       - $ref: '#/components/schemas/uiNodeAnchorAttributes'
       - $ref: '#/components/schemas/uiNodeScriptAttributes'
       title: Attributes represents a list of attributes (e.g. `href="foo"` for links).
-    uiNodeGroup:
-      type: string
     uiNodeImageAttributes:
       properties:
         height:
@@ -5108,6 +5136,15 @@ components:
           description: A unique identifier
           type: string
         node_type:
+          description: |-
+            NodeType represents this node's types. It is a mirror of `node.type` and
+            is primarily used to allow compatibility with OpenAPI 3.0.
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
         src:
           description: |-
@@ -5141,6 +5178,15 @@ components:
           description: The input's element name.
           type: string
         node_type:
+          description: |-
+            NodeType represents this node's types. It is a mirror of `node.type` and
+            is primarily used to allow compatibility with OpenAPI 3.0.
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
         onclick:
           description: |-
@@ -5194,6 +5240,15 @@ components:
           description: The script's integrity hash
           type: string
         node_type:
+          description: |-
+            NodeType represents this node's types. It is a mirror of `node.type` and
+            is primarily used to allow compatibility with OpenAPI 3.0.
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
         nonce:
           description: |-
@@ -5230,6 +5285,15 @@ components:
           description: A unique identifier
           type: string
         node_type:
+          description: |-
+            NodeType represents this node's types. It is a mirror of `node.type` and
+            is primarily used to allow compatibility with OpenAPI 3.0.
+          enum:
+          - text
+          - input
+          - img
+          - a
+          - script
           type: string
         text:
           $ref: '#/components/schemas/uiText'
@@ -5239,8 +5303,6 @@ components:
       - text
       title: TextAttributes represents the attributes of a text node.
       type: object
-    uiNodeType:
-      type: string
     uiNodes:
       items:
         $ref: '#/components/schemas/uiNode'

diff --git a/internal/httpclient/docs/SelfServiceRecoveryFlow.md b/internal/httpclient/docs/SelfServiceRecoveryFlow.md
@@ -11,14 +11,14 @@ Name | Type | Description | Notes
 **RequestUrl** | **string** | RequestURL is the initial URL that was requested from Ory Kratos. It can be used to forward information contained in the URL&#39;s path or query for example. | 
 **ReturnTo** | Pointer to **string** | ReturnTo contains the requested return_to URL. | [optional] 
 **State** | [**SelfServiceRecoveryFlowState**](SelfServiceRecoveryFlowState.md) |  | 
-**Type** | Pointer to **string** | The flow type can either be &#x60;api&#x60; or &#x60;browser&#x60;. | [optional] 
+**Type** | **string** | The flow type can either be &#x60;api&#x60; or &#x60;browser&#x60;. | 
 **Ui** | [**UiContainer**](UiContainer.md) |  | 
 
 ## Methods
 
 ### NewSelfServiceRecoveryFlow
 
-`func NewSelfServiceRecoveryFlow(expiresAt time.Time, id string, issuedAt time.Time, requestUrl string, state SelfServiceRecoveryFlowState, ui UiContainer, ) *SelfServiceRecoveryFlow`
+`func NewSelfServiceRecoveryFlow(expiresAt time.Time, id string, issuedAt time.Time, requestUrl string, state SelfServiceRecoveryFlowState, type_ string, ui UiContainer, ) *SelfServiceRecoveryFlow`
 
 NewSelfServiceRecoveryFlow instantiates a new SelfServiceRecoveryFlow object
 This constructor will assign default values to properties that have it defined,
@@ -202,11 +202,6 @@ and a boolean to check if the value has been set.
 
 SetType sets Type field to given value.
 
-### HasType
-
-`func (o *SelfServiceRecoveryFlow) HasType() bool`
-
-HasType returns a boolean if a field has been set.
 
 ### GetUi