Merge branch 'master' into howto-single-project

changelog/2025-01-09-api-changes-v2.mdx

@@ -7,18 +7,15 @@ tags:
   - breaking
   - Conversation
   - Marketplace
-
 ---
 
 import OperationHint from "@site/src/components/OperationHint";
 import OperationLink from "@site/src/components/OperationLink";
 
-On January 9, 2025, the mittwald API introduced several changes, including the removal of the 'project_email_admin' enum value from various properties, the addition of the 'project_emailadmin' enum value, the removal of a schema, and the introduction of a new endpoint for listing extensions of a contributor.
+On January 9, 2025, the mittwald API introduced several changes, including the removal of the `project_email_admin` enum value from various properties, the addition of the `project_emailadmin` enum value, the removal of a schema, and the introduction of a new endpoint for listing extensions of a contributor.
 
 {/* truncate */}
 
-
-
 :::caution Breaking changes
 
 This document contains changes that can under certain circumstances be considered breaking. Please review the changes carefully.
@@ -27,103 +24,66 @@ While we generally strive to avoid breaking changes in accordance with our [API
 
 :::
 
-
-
 ## Summary
 
-
-- The enum value 'project_email_admin' has been removed from the request property 'notificationRoles/items/' in the POST operation for creating a conversation. This is a breaking change.
-- A new enum value 'project_emailadmin' has been added to the response property 'notificationRoles/items/' for the GET operation to list all conversations and for the GET operation to get a specific conversation.
-- The enum value 'project_email_admin' has been removed from the response property 'notificationRoles/items/' for the GET operations to list all conversations and to get a specific conversation.
-- A new enum value 'project_emailadmin' has been added to the request property 'notificationRoles/items/' in the POST operation for creating a conversation.
-- The schema 'de.mittwald.v1.conversation.DepartmentWithStatus' has been removed from the API schema.
-- A new endpoint has been added to list extensions of a contributor with the GET operation at the path '/v2/contributors/{contributorId}/extensions'.
-- The response property 'oneOf' list for the response status '200' has been updated to include '#/components/schemas/de.mittwald.v1.conversation.ServiceRequest' in the GET operation to list messages by conversation.
+- The enum value `project_email_admin` has been removed from the request property `notificationRoles/items/` in the POST operation for creating a conversation. This is a breaking change.
+- A new enum value `project_emailadmin` has been added to the response property `notificationRoles/items/` for the GET operation to list all conversations and for the GET operation to get a specific conversation.
+- The enum value `project_email_admin` has been removed from the response property `notificationRoles/items/` for the GET operations to list all conversations and to get a specific conversation.
+- A new enum value `project_emailadmin` has been added to the request property `notificationRoles/items/` in the POST operation for creating a conversation.
+- The schema `de.mittwald.v1.conversation.DepartmentWithStatus` has been removed from the API schema.
+- A new endpoint has been added to list extensions of a contributor with the GET operation at the path `/v2/contributors/{contributorId}/extensions`.
+- The response property `oneOf` list for the response status `200` has been updated to include `#/components/schemas/de.mittwald.v1.conversation.ServiceRequest` in the GET operation to list messages by conversation.
 
 _Disclaimer: This summary is AI-generated. If you find any discrepancies, please refer to the detailed changes below._
 
-
 ## Detailed changes
 
-
-
 ### Changes in "Create a conversation"
 
+- ⚠️ **Breaking:** removed the enum value `project_email_admin` of the request property `notificationRoles/items/`
 
-- ⚠️ **Breaking:** removed the enum value 'project_email_admin' of the request property 'notificationRoles/items/'
-
-- added the new 'project_emailadmin' enum value to the request property 'notificationRoles/items/'
-
+- added the new `project_emailadmin` enum value to the request property `notificationRoles/items/`
 
 For details, refer to the <OperationLink operation="conversation-create-conversation" apiVersion="v2" /> endpoint.
 
-
-
 ### Changes in "Get all conversation the authenticated user has created or has access to"
 
+- added the new `project_emailadmin` enum value to the `/items/notificationRoles/items/` response property for the response status `200`
 
-- added the new 'project_emailadmin' enum value to the '/items/notificationRoles/items/' response property for the response status '200'
-
-- removed the 'project_email_admin' enum value from the '/items/notificationRoles/items/' response property for the response status '200'
-
+- removed the `project_email_admin` enum value from the `/items/notificationRoles/items/` response property for the response status `200`
 
 For details, refer to the <OperationLink operation="conversation-list-conversations" apiVersion="v2" /> endpoint.
 
-
-
 ### Changes in "Get a support conversation"
 
+- added the new `project_emailadmin` enum value to the `notificationRoles/items/` response property for the response status `200`
 
-- added the new 'project_emailadmin' enum value to the 'notificationRoles/items/' response property for the response status '200'
-
-- removed the 'project_email_admin' enum value from the 'notificationRoles/items/' response property for the response status '200'
-
+- removed the `project_email_admin` enum value from the `notificationRoles/items/` response property for the response status `200`
 
 For details, refer to the <OperationLink operation="conversation-get-conversation" apiVersion="v2" /> endpoint.
 
-
-
-### Changes in ""
-
-
-- removed the schema 'de.mittwald.v1.conversation.DepartmentWithStatus'
-
-
-For details, refer to the <OperationLink operation="" apiVersion="v2" /> endpoint.
-
-
-
 ### Changes in "List Extensions of own contributor"
 
-
 - endpoint added
 
-
 For details, refer to the <OperationLink operation="extension-list-own-extensions" apiVersion="v2" /> endpoint.
 
-
-
 ### Changes in "Get all message of the conversation"
 
-
-- added '#/components/schemas/de.mittwald.v1.conversation.ServiceRequest' to the '/items/' response property 'oneOf' list for the response status '200'
-
+- added `#/components/schemas/de.mittwald.v1.conversation.ServiceRequest` to the `/items/` response property `oneOf` list for the response status `200`
 
 For details, refer to the <OperationLink operation="conversation-list-messages-by-conversation" apiVersion="v2" /> endpoint.
 
-
-
-
 ## Client package releases
 
-
 ### mittwald PHP SDK Release v2.1.90
 
 The mittwald PHP SDK has been updated to version v2.1.90. This release introduces several new features and improvements:
 
 #### Added Features
 
 - **New API Request and Response Handling for Listing Own Extensions**:
+
   - Implemented a client for fetching a contributor's extensions, including:
     - `ExtensionListOwnExtensionsRequest`: A request object for listing extensions with pagination and limit parameters.
     - `ExtensionListOwnExtensionsOKResponse`: A successful response containing an array of `OwnExtension` objects.
@@ -148,4 +108,3 @@ For more details, visit the [release page](https://github.com/mittwald/api-clien
 ### mittwald JavaScript SDK Release 4.90.0
 
 The mittwald JavaScript SDK has been updated to version 4.90.0. This release includes an update to the generated client, enhancing the SDK's functionality. For more details, you can view the release on GitHub: [mittwald JavaScript SDK 4.90.0](https://github.com/mittwald/api-client-js/releases/tag/4.90.0).
-

generator/overlays/v2/container-declare-stack/description.mdx

@@ -2,7 +2,7 @@ This command can be used to declare the desired state of a container stack.
 
 :::important Idempotent operation
 
-This operation is idempotent and can be used to add/update or remove containers and volumes from a stack. To remove a container, replace the container definition with an empty object.
+This operation is idempotent and can be used to add/update or remove containers and volumes from a stack. To remove a container, remove it from the definition list when replacing the container stack.
 
 :::
 

generator/overlays/v2/container.mdx

@@ -40,6 +40,13 @@ Containers are run as part of a container stack. A container stack is a collecti
 - <OperationLink operation="container-list-stacks" apiVersion="v2-preview" /> to list available stacks (use the `default` stack)
 - <OperationLink operation="container-declare-stack" apiVersion="v2-preview" /> to declare the desired state of a container stack; this operation is idempotent and can be used to add/update or remove containers and volumes from a stack
 
+### Connecting domains to containers
+
+To connect a domain to a running container, you can specify the container as target of an ingress resource. Use the following API operation to create an ingress connected to a container:
+
+<!-- prettier-ignore -->
+- <OperationLink operation="ingress-create-ingress" apiVersion="v2" /> to connect a domain to a container
+
 ## Operational tasks
 
 To manage a container stack's lifecycle, you can use the following API operations:

generator/overlays/v2/overlay.yaml

@@ -71,4 +71,60 @@ actions:
     update:
       summary: Resets A records to managed for a specific zone
       description: >
-        This operation is deprecated. Use the `POST /v2/dns/zones/{zoneId}/record-sets/{recordSet}/actions/set-managed` endpoint instead.
+        This operation is deprecated. Use the `POST /v2/dns/zones/{zoneId}/record-sets/{recordSet}/actions/set-managed` endpoint instead.
+
+  - target: $.paths['/v2/ingresses'].post.requestBody.content['application/json'].schema.properties.paths
+    update:
+      example:
+        - path: /
+          target:
+            useDefaultPage: true
+        - path: /redirect
+          target:
+            url: https://some-redirect.example
+        - path: /path-to-dir
+          target:
+            directory: /public
+        - path: /path-to-app
+          target:
+            installationId: e1ccfde2-8983-4529-ae66-23a7e34c1177
+        - path: /path-to-container
+          target:
+            container:
+              id: ead3223c-6f23-4eaf-8250-392f10b49a35
+              portProtocol: 80/tcp
+  - target: $.components.schemas['de.mittwald.v1.ingress.TargetDirectory']
+    update:
+      description: Serve files from a specific directory
+      properties:
+        directory:
+          description: The directory from which to serve files.
+          example: /public
+  - target: $.components.schemas['de.mittwald.v1.ingress.TargetUrl']
+    update:
+      description: Redirect requests to this path to another URL
+      properties:
+        url:
+          description: The URL to which requests should be forwarded.
+          example: https://redirect-target.example
+  - target: $.components.schemas['de.mittwald.v1.ingress.TargetInstallation']
+    update:
+      description: Serve a specific app installation
+      properties:
+        installationId:
+          description: The ID of an app installation within the same project to which requests should be forwarded.
+  - target: $.components.schemas['de.mittwald.v1.ingress.TargetUseDefaultPage']
+    update:
+      description: Serve a generic default page
+      properties:
+        useDefaultPage:
+          description: Set this to `true` to serve a generic default site at this path.
+  - target: $.components.schemas['de.mittwald.v1.ingress.TargetContainer']
+    update:
+      description: Forward requests to this path to a specific container.
+      properties:
+        container:
+          descriptions: References a specific port/container combination within the same project.
+          properties:
+            portProtocol:
+              example: 80/tcp

package.json

@@ -24,7 +24,7 @@
     "@docusaurus/preset-classic": "^3.7.0",
     "@docusaurus/theme-mermaid": "^3.7.0",
     "@mdx-js/react": "^3.0.0",
-    "@mittwald/flow-react-components": "^0.1.0-alpha.391",
+    "@mittwald/flow-react-components": "^0.1.0-alpha.393",
     "clsx": "^2.1.1",
     "openapi-types": "^12.1.3",
     "prism-react-renderer": "^2.4.1",
@@ -48,7 +48,7 @@
     "openai": "^4.77.3",
     "prettier": "^3.4.2",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.3"
   },
   "browserslist": {
     "production": [

src/components/openapi/OperationInputValue.tsx

@@ -14,12 +14,19 @@ export function AlternativeValue({
 }: {
   schema: OpenAPIV3.SchemaObject;
 }) {
+  let body: ReactNode;
+
+  if (schema.description) {
+    body = <Markdown>{schema.description}</Markdown>;
+  }
+
   return (
     <li>
       <div className={styles.parameterListHeader}>
         <span className={styles.parameterAlternative}>Alternative</span>
         <Type className={styles.parameterType} schema={schema} />
       </div>
+      {body && <div className={styles.parameterListBody}>{body}</div>}
       <Schema schema={schema} />
     </li>
   );
@@ -63,7 +70,10 @@ export function PropertyValue({
   }
 
   const hasSubSchema =
-    schema.properties || schema.additionalProperties || schema.items;
+    schema.properties ||
+    schema.additionalProperties ||
+    schema.items ||
+    schema.oneOf;
 
   return (
     <li key={name}>

src/openapi/generateSchemaExample.ts

@@ -43,6 +43,8 @@ export function generateSchemaExample(schema: OpenAPIV3.SchemaObject): any {
       return "[email protected]";
     } else if (schema.format === "uuid") {
       return "f0f86186-0a5a-45b2-aa33-502777496347";
+    } else if (schema.format === "idn-hostname") {
+      return "some-hostname.example";
     }
 
     if (schema.enum !== undefined) {