[#48966] refactored help text api models

- https://community.openproject.org/work_packages/48966

.redocly.lint-ignore.yaml

@@ -6,6 +6,7 @@ tmp/oas-generated.yml:
     - '#/paths/~1api~1v3~1file_links~1{file_link_id}~1open/get/responses'
   operation-4xx-response:
     - '#/paths/~1api~1v3/get/responses'
+    - '#/paths/~1api~1v3~1help_texts/get/responses'
   no-ambiguous-paths:
     - '#/paths/~1api~1v3~1queries~1{id}~1form'
     - '#/paths/~1api~1v3~1queries~1{id}~1star'

docs/api/apiv3/components/schemas/help_text_collection_model.yml

@@ -0,0 +1,64 @@
+# Schema: HelpTextCollectionModel
+---
+allOf:
+  - $ref: './collection_model.yml'
+  - type: object
+    required:
+      - _links
+      - _embedded
+    properties:
+      _links:
+        type: object
+        required:
+          - self
+        properties:
+          self:
+            allOf:
+              - $ref: "./link.yml"
+              - description: |-
+                  This help text collection
+                  
+                  **Resource**: HelpTextCollectionModel
+      _embedded:
+        type: object
+        required:
+          - elements
+        properties:
+          elements:
+            type: array
+            items:
+              $ref: './help_text_model.yml'
+
+example:
+  total: 2
+  count: 2
+  _type: Collection
+  _embedded:
+    elements:
+      - _type: HelpText
+        _links:
+          self:
+            href: "/api/v3/help_texts/1"
+        id: 1
+        attribute: id
+        attributeCaption: ID
+        scope: WorkPackage
+        helpText:
+          format: markdown
+          raw: Help text for id attribute.
+          html: "<p>Help text for id attribute.</p>"
+      - _type: HelpText
+        _links:
+          self:
+            href: "/api/v3/help_texts/2"
+        id: 2
+        attribute: status
+        attributeCaption: Status
+        scope: WorkPackage
+        helpText:
+          format: markdown
+          raw: Help text for status attribute.
+          html: "<p>Help text for status attribute.</p>"
+  _links:
+    self:
+      href: "/api/v3/help_texts"

docs/api/apiv3/components/schemas/help_text_model.yml

@@ -1,19 +1,84 @@
-# Schema: Help_textModel
+# Schema: HelpTextModel
 ---
 type: object
+required:
+  - _type
+  - id
+  - attribute
+  - scope
+  - helpText
+  - _links
+properties:
+  _type:
+    type: string
+    enum:
+      - HelpText
+  id:
+    type: integer
+    format: int64
+    minimum: 1
+  attribute:
+    type: string
+    description: The attribute the help text is assigned to.
+  scope:
+    type: string
+    enum:
+      - WorkPackage
+      - Project
+  helpText:
+    $ref: './formattable.yml'
+  _links:
+    type: object
+    required:
+      - self
+      - editText
+      - attachments
+      - addAttachment
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This help text resource.
+
+              **Resource**: HelpText
+      editText:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              Edit the help text entry.
+
+              **Resource**: text/html
+      attachments:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The attachment collection of this help text.
+
+              **Resource**: AttachmentCollection
+      addAttachment:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              Add an attachment to the help text.
+
 example:
   _type: HelpText
-  _links:
-    self:
-      href: "/api/v3/help_texts/1"
-    editText:
-      type: text/html
-      href: "/admin/attribute_help_texts/1/edit"
   id: 1
   attribute: id
-  attributeCaption: ID
   scope: WorkPackage
   helpText:
     format: markdown
     raw: Help text for id attribute.
-    html: "<p>Help text for id attribute.</p>"
+    html: '<p>Help text for id attribute.</p>'
+  _links:
+    self:
+      href: '/api/v3/help_texts/1'
+    editText:
+      href: '/admin/attribute_help_texts/1/edit'
+      type: text/html
+    attachments:
+      href: '/api/v3/help_texts/1/attachments'
+    addAttachments:
+      href: '/api/v3/help_texts/1/attachments'
+      method: post

docs/api/apiv3/components/schemas/help_texts_model.yml

@@ -1,36 +0,0 @@
-# Schema: Help_textsModel
----
-type: object
-example:
-  _links:
-    self:
-      href: "/api/v3/help_texts"
-  total: 2
-  count: 2
-  _type: Collection
-  _embedded:
-    elements:
-    - _type: HelpText
-      _links:
-        self:
-          href: "/api/v3/help_texts/1"
-      id: 1
-      attribute: id
-      attributeCaption: ID
-      scope: WorkPackage
-      helpText:
-        format: markdown
-        raw: Help text for id attribute.
-        html: "<p>Help text for id attribute.</p>"
-    - _type: HelpText
-      _links:
-        self:
-          href: "/api/v3/help_texts/2"
-      id: 2
-      attribute: status
-      attributeCaption: Status
-      scope: WorkPackage
-      helpText:
-        format: markdown
-        raw: Help text for status attribute.
-        html: "<p>Help text for status attribute.</p>"

docs/api/apiv3/openapi-spec.yml

@@ -583,10 +583,10 @@ components:
       "$ref": "./components/schemas/group_model.yml"
     GroupWriteModel:
       "$ref": "./components/schemas/group_write_model.yml"
-    Help_textModel:
+    HelpTextCollectionModel:
+      "$ref": "./components/schemas/help_text_collection_model.yml"
+    HelpTextModel:
       "$ref": "./components/schemas/help_text_model.yml"
-    Help_textsModel:
-      "$ref": "./components/schemas/help_texts_model.yml"
     Link:
       "$ref": "./components/schemas/link.yml"
     List_actionsModel:

docs/api/apiv3/paths/help_text.yml

@@ -1,42 +1,34 @@
 # /api/v3/help_texts/{id}
 ---
 get:
+  summary: Get help text
+  operationId: get_help_text
+  tags:
+    - Help texts
+  description: Fetches the help text from the given id.
   parameters:
-  - description: Help text id
-    example: '1'
-    in: path
-    name: id
-    required: true
-    schema:
-      type: integer
+    - name: id
+      description: Help text id
+      example: 1
+      in: path
+      required: true
+      schema:
+        type: integer
   responses:
     '200':
+      description: OK
       content:
         application/hal+json:
-          examples:
-            response:
-              value:
-                _links:
-                  editText:
-                    href: "/admin/attribute_help_texts/1/edit"
-                    type: text/html
-                  self:
-                    href: "/api/v3/help_texts/1"
-                _type: HelpText
-                attribute: id
-                attributeCaption: ID
-                helpText:
-                  format: markdown
-                  html: "<p>Help text for id attribute.</p>"
-                  raw: Help text for id attribute.
-                id: 1
-                scope: WorkPackage
           schema:
-            "$ref": "../components/schemas/help_text_model.yml"
-      description: OK
-      headers: {}
-  tags:
-  - Help texts
-  description: ''
-  operationId: View_help_text
-  summary: View help text
+            $ref: '../components/schemas/help_text_model.yml'
+    '404':
+      description: |-
+        Returned if the help text does not exist.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+            message: The requested resource could not be found.

docs/api/apiv3/paths/help_texts.yml

@@ -1,51 +1,15 @@
 # /api/v3/help_texts
 ---
 get:
+  summary: List help texts
+  operationId: list_help_texts
+  tags:
+    - Help texts
+  description: List the complete collection of help texts.
   responses:
     '200':
+      description: OK
       content:
         application/hal+json:
-          examples:
-            response:
-              value:
-                _embedded:
-                  elements:
-                  - _links:
-                      self:
-                        href: "/api/v3/help_texts/1"
-                    _type: HelpText
-                    attribute: id
-                    attributeCaption: ID
-                    helpText:
-                      format: markdown
-                      html: "<p>Help text for id attribute.</p>"
-                      raw: Help text for id attribute.
-                    id: 1
-                    scope: WorkPackage
-                  - _links:
-                      self:
-                        href: "/api/v3/help_texts/2"
-                    _type: HelpText
-                    attribute: status
-                    attributeCaption: Status
-                    helpText:
-                      format: markdown
-                      html: "<p>Help text for status attribute.</p>"
-                      raw: Help text for status attribute.
-                    id: 2
-                    scope: WorkPackage
-                _links:
-                  self:
-                    href: "/api/v3/help_texts"
-                _type: Collection
-                count: 2
-                total: 2
           schema:
-            "$ref": "../components/schemas/help_texts_model.yml"
-      description: OK
-      headers: {}
-  tags:
-  - Help texts
-  description: ''
-  operationId: List_all_help_texts
-  summary: List all help texts
+            $ref: '../components/schemas/help_text_collection_model.yml'