archsight 0.4.0 → 0.4.2

data/lib/archsight/openapi.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require_relative "resources"
+
+module Archsight
+  # The OpenAPI document of the REST API: the hand-written base (`web/api/openapi/spec.yaml`: the fixed endpoints such
+  # as pages, assets, search and the editor, with their prose, examples and error shapes) plus what the model knows and
+  # nobody should type twice: one schema per kind with its annotations (type, enum, description, default), its `spec`
+  # relations and its relations, the list of kinds, and the instance detail schema that is one of them. A new kind, a
+  # changed enum or another relation shows up in the documentation without touching the YAML.
+  #
+  #   Archsight::OpenAPI.document # => Hash, `.to_yaml` is what GET /api/v1/openapi.yaml serves
+  module OpenAPI
+    BASE = File.join(__dir__, "web", "api", "openapi", "spec.yaml")
+
+    # The operations that answer with the detail of one instance, whose kind the path names
+    DETAIL_PATHS = ["/api/v1/kinds/{kind}/instances/{name}", "/kinds/{kind}/instances/{name}.json"].freeze
+
+    # What an annotation of a type is in the JSON. The value is the one of the YAML file, so a number may also be its
+    # string ("100"); only a computed annotation is always a number. Everything else is a string.
+    TYPES = {
+      Integer => { "type" => %w[integer string] },
+      Float => { "type" => %w[number string] }
+    }.freeze
+
+    NAMES = { "type" => "array", "items" => { "type" => "string" } }.freeze
+
+    class << self
+      # @return [Hash] the complete document; built once, the model does not change while the server runs
+      def document
+        @document ||= build
+      end
+
+      # Forget the built document (the model was changed, in a test)
+      def reset!
+        @document = nil
+      end
+
+      # The name of the schema of a kind
+      def schema_name(kind) = "#{kind}Instance"
+
+      # The schema of one kind: the detail of an instance as GET /api/v1/kinds/{kind}/instances/{name} returns it
+      # @param kind [String] name of a kind
+      # @return [Hash]
+      def kind_schema(kind)
+        klass = Archsight::Resources[kind]
+        schema = {
+          "type" => "object",
+          "required" => %w[kind name metadata spec relations references],
+          "x-layer" => klass.layer,
+          "properties" => {
+            "kind" => { "type" => "string", "const" => kind },
+            "name" => { "type" => "string", "description" => "Name of the instance" },
+            "metadata" => { "type" => "object", "properties" => { "annotations" => annotations_schema(klass) } },
+            "annotation_formats" => { "type" => "object", "additionalProperties" => { "type" => "string" },
+                                      "description" => "How the UI shows each annotation that is set (markdown, link, tag_list, ...)" },
+            "annotation_links" => { "type" => "object", "additionalProperties" => true,
+                                    "description" => "Annotations whose value names resources, with the resources they resolve to" },
+            "spec" => spec_schema(klass),
+            "relations" => relations_schema(klass),
+            "references" => references_schema,
+            "diagram" => { "type" => %w[string null], "description" => "The `architecture/diagram` annotation as inline SVG" }
+          }
+        }
+        schema["description"] = klass.description.strip if klass.description
+        schema
+      end
+
+      private
+
+      def build
+        document = YAML.safe_load_file(BASE, permitted_classes: [], aliases: true)
+        kinds = Archsight::Resources.resource_classes.keys.sort
+        schemas = document.fetch("components").fetch("schemas")
+        add_schemas(schemas, kinds)
+        document.dig("components", "parameters", "kind")["schema"] = { "$ref" => "#/components/schemas/KindName" }
+        DETAIL_PATHS.each { |path| use_detail_schema(document.fetch("paths").fetch(path)) }
+        # the schemas share small hashes: a copy of each keeps YAML from writing anchors and aliases for them
+        JSON.parse(JSON.generate(document))
+      end
+
+      def add_schemas(schemas, kinds)
+        kinds.each do |kind|
+          name = schema_name(kind)
+          raise ArgumentError, "OpenAPI: the schema #{name} of #{kind} clashes with a schema of the base spec" if schemas.key?(name)
+
+          schemas[name] = kind_schema(kind)
+        end
+        schemas["KindName"] = {
+          "type" => "string", "enum" => kinds,
+          "description" => "Name of a resource kind. A kind that was renamed is still accepted under its old name."
+        }
+        schemas["InstanceDetail"] = {
+          "description" => "An instance with its relations and references: the schema depends on the kind",
+          "oneOf" => kinds.map { |kind| { "$ref" => "#/components/schemas/#{schema_name(kind)}" } },
+          "discriminator" => { "propertyName" => "kind", "mapping" => kinds.to_h { |kind| [kind, "#/components/schemas/#{schema_name(kind)}"] } }
+        }
+      end
+
+      def use_detail_schema(path_item)
+        path_item.dig("get", "responses", "200", "content", "application/json")["schema"] = { "$ref" => "#/components/schemas/InstanceDetail" }
+      end
+
+      # The annotations of the kind that are set; every annotation is optional. Other annotations are allowed.
+      def annotations_schema(klass)
+        fixed, patterns = klass.annotations.partition { |annotation| !annotation.pattern? }
+        schema = {
+          "type" => "object", "additionalProperties" => true,
+          "properties" => fixed.to_h { |annotation| [annotation.key, annotation_schema(annotation)] }
+        }
+        schema["patternProperties"] = patterns.to_h { |annotation| [pattern_of(annotation.key), annotation_schema(annotation)] } unless patterns.empty?
+        schema
+      end
+
+      def annotation_schema(annotation)
+        schema = (TYPES[annotation.type] || { "type" => "string" }).dup
+        description = annotation.description.to_s.strip
+        description = "#{description}\n\nRendered to HTML in the response." if annotation.format == :markdown && !description.empty?
+        schema["description"] = description unless description.empty?
+        if annotation.enum && annotation.list?
+          # a list is one string of comma separated values, each of them one of the enum
+          schema["description"] = "#{description}\n\nComma separated list of: #{annotation.enum.join(", ")}.".strip
+          schema["x-items-enum"] = annotation.enum
+        elsif annotation.enum
+          schema["enum"] = annotation.enum
+        end
+        schema["default"] = annotation.default unless annotation.default.nil?
+        schema["deprecated"] = true if annotation.deprecated
+        schema
+      end
+
+      # `link/*` -> a regular expression for the keys it matches
+      def pattern_of(key) = "^#{Regexp.escape(key).gsub('\*', ".+")}$"
+
+      # What the file says: spec.<verb>.<key>: [names]
+      def spec_schema(klass)
+        properties = {}
+        klass.declared_relations.each do |verb, key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object", "properties" => {} })
+          verb_schema["properties"][key.to_s] = NAMES.merge("description" => "Names of #{target} resources")
+        end
+        { "type" => "object", "additionalProperties" => true, "properties" => properties,
+          "description" => "The relations as written in the resource: verb, then the kind's collection, then the names" }
+      end
+
+      # The outgoing relations that exist: verb, then the kind of the target, then the names
+      def relations_schema(klass)
+        properties = {}
+        klass.relations.each do |verb, _key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object" })
+          if Archsight::Resources::DERIVED_VERBS.include?(verb)
+            verb_schema["additionalProperties"] = NAMES # targets of any kind, grouped by the kind they are
+          else
+            (verb_schema["properties"] ||= {})[target.to_s] = NAMES
+          end
+        end
+        { "type" => "object", "additionalProperties" => false, "properties" => properties,
+          "description" => "Outgoing relations that have targets, grouped by verb and the kind of the target" }
+      end
+
+      def references_schema
+        { "type" => "object", "additionalProperties" => { "type" => "object", "additionalProperties" => NAMES },
+          "description" => "Incoming relations grouped by the kind of the source and the verb" }
+      end
+    end
+  end
+end

data/lib/archsight/page_tree.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "markdown"
 
 module Archsight
   # PageTree builds the sidebar tree, breadcrumbs and tables of contents for Page resources
@@ -63,7 +62,7 @@ module Archsight
 
     # Flat table of contents [{level:, id:, text:}] of a markdown body
     def self.toc(markdown)
-      doc = Kramdown::Document.new(markdown.to_s, input: "GFM")
+      doc = Archsight::Markdown.document(markdown)
       entries = [] #: Array[Hash[String, untyped]]
       collect_toc(doc.to_toc, entries)
       entries

data/lib/archsight/resources/application_component.rb

@@ -62,6 +62,13 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     importers write the service per component, so a sidecar or agent deployed into many clusters shows where it runs
     without making its own service look like it runs in all of them.
 
+    A component that creates technology services is `provisions` them: a controller, operator, pipeline or job that
+    builds and reconciles the clusters, database clusters or VM pools of a product (Crossplane, Cluster API, a
+    Terraform controller). It is written on the component, which points down to what it creates, like `servedBy`; the
+    service page lists the component as incoming "provisions". `servedBy` says where the component itself runs,
+    `provisions` what it builds, and a service that is built elsewhere keeps running while its provisioner is down,
+    only changes stop. The impact of a provisioner is what it reaches: its outgoing relations.
+
     The computed `component/dependents` counts the components that depend on this one, which tells shared libraries
     and modules from components nobody consumes.
 
@@ -418,6 +425,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :realizedBy, :technologyComponents, :TechnologyNode
   relation :servedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :technologyServices, :TechnologyService
+  relation :provisions, :technologyServices, :TechnologyService
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent

data/lib/archsight/resources/application_interface.rb

@@ -25,6 +25,17 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
     - gRPC services
     - Message queues (producer/consumer interfaces)
     - WebSocket endpoints
+
+    ## Reachability
+
+    An interface is `servedBy` the `TechnologyInterface` that carries it (a protocol, an authentication method) and
+    by the `TechnologyCommunicationNetwork`s on which it can be reached, just as a `TechnologyNode` attaches to the
+    networks it is on. Together with `api/authenticationMethod` this decides the exposure of the interface: an
+    interface without authentication on an internal network is a different risk than on a network that
+    internet-facing components attach to. The network page lists the interfaces as incoming "served by".
+
+    Write the networks only when they are known. An interface without a network makes no claim about where it can
+    be reached.
   MD
 
   icon "usb"
@@ -47,6 +58,7 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
+  relation :servedBy, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :dataObjects, :DataObject
 end

data/lib/archsight/resources/technology_communication_network.rb

@@ -50,6 +50,8 @@ class Archsight::Resources::TechnologyCommunicationNetwork < Archsight::Resource
     - An overlay that software builds is `realizedBy` that `ApplicationComponent` or `ApplicationService` (an SDN agent,
       a network operator, a load-balancer controller), also when the software runs on the nodes the network serves
     - A `TechnologyNode` is `servedBy` the networks it is attached to; the network page lists them
+    - An `ApplicationInterface` is `servedBy` the networks on which it can be reached (only when that is known); the
+      network page lists the interfaces, which shows what a network exposes
     - A network is `realizedBy` the `TechnologyDevice`s that build it (its switches and routers) and `connects` the
       devices attached to it (servers, firewalls, appliances). Both are written on the network, so a switch that is
       also attached to the network it builds closes no cycle

data/lib/archsight/resources/technology_device.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-# TechnologyDevice represents one physical machine: a server, switch, router, firewall or appliance
+# TechnologyDevice represents one physical machine: a server, switch, router, firewall, appliance or client machine
 class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
   include_annotations :git, :architecture, :asset, :risk
 
   description <<~MD
-    Represents one physical machine: a server, a switch, a router, a firewall, a terminal server or an appliance.
+    Represents one physical machine: a server, a switch, a router, a firewall, a terminal server, an appliance, or a
+    client machine (a laptop, a workstation, a phone).
 
     ## ArchiMate Definition
 
@@ -18,13 +19,34 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
     ## Usage
 
     Use TechnologyDevice when the individual machine matters: which room it stands in, which switch it is cabled to,
-    which machines a failure domain loses.
+    which machines a failure domain loses, which operating system and owner a workstation has.
 
     - One element per physical machine (name it after the host: "Device:Frankfurt:Server01")
     - A group of machines with one role ("the hypervisors of the platform") stays a logical `TechnologyNode` that is
       `realizedBy` its devices
     - A virtual chassis, a stack or a cluster pair is a device `composedOf` its member devices
 
+    ## Client devices
+
+    A developer workstation, a laptop, a thin client, a tablet or a phone is a device of the matching `device/type`;
+    `device/os`, `device/osVersion` and `device/arch` say what it runs on, `device/ownership` whether the company
+    owns it, `device/managed` whether it is centrally managed (MDM) and `device/encryption` whether the disk is
+    encrypted. The vendor and product go into `device/model`, also for a hardened workstation that runs the user's
+    operating system virtualized next to other isolated sessions: it is a `workstation`. The end of support is
+    `lifecycle/endOfLifeAt`, a group of machines is a tag (`architecture/tags`).
+
+    - Model the individual machine when it is inventoried (an MDM import can write them), otherwise one
+      `TechnologyNode` per client platform ("Node:Workstation:macOS") `realizedBy` the devices
+    - The operating system is `TechnologySystemSoftware` `realizedBy` that node; the image or packages it is
+      installed from are `TechnologyArtifact`s the node is `assignedTo`. Each isolated session of a hardened
+      workstation can be a node of its own, `realizedBy` the device
+    - Network access: the platform node is `servedBy` the networks it uses (the office, the VPN), a single named
+      machine is `connects`-ed by its network (the VPN it tunnels through, an isolated segment). A machine that
+      reaches no network (air-gapped) has neither relation. The device itself does not point to networks: a network
+      is `realizedBy` its switches, so the reverse arrow would close a cycle
+    - Who uses it is the team or role (`servedBy`), not a person; a client device needs no room, `locatedAt` an
+      office is optional
+
     ## Not this kind
 
     - A VM, a Kubernetes node or a host role is a `TechnologyNode`
@@ -57,7 +79,7 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
   annotation "device/type",
              description: "Kind of device",
              title: "Device Type",
-             enum: %w[server switch router firewall terminal-server appliance other],
+             enum: %w[server switch router firewall terminal-server appliance laptop desktop workstation thin-client tablet mobile other],
              filter: :word,
              summary: true
   annotation "device/role",
@@ -79,6 +101,36 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
              title: "Purpose",
              filter: :word
 
+  annotation "device/os",
+             description: "Operating system family of a client device",
+             title: "Operating System",
+             enum: %w[windows macos linux freebsd openbsd netbsd android ios chromeos other],
+             filter: :word,
+             summary: true
+  annotation "device/osVersion",
+             description: "Operating system version, e.g. 15.1 or 24.04 LTS",
+             title: "OS Version"
+  annotation "device/arch",
+             description: "CPU architecture",
+             title: "Architecture",
+             enum: %w[x86_64 arm64 riscv64 other],
+             filter: :word
+  annotation "device/ownership",
+             description: "Who owns the device",
+             title: "Ownership",
+             enum: %w[company-owned leased byod],
+             filter: :word
+  annotation "device/managed",
+             description: "Whether the device is managed centrally (MDM, configuration management)",
+             title: "Managed",
+             enum: %w[managed unmanaged],
+             filter: :word
+  annotation "device/encryption",
+             description: "Whether the disk is encrypted",
+             title: "Disk Encryption",
+             enum: %w[enabled disabled],
+             filter: :word
+
   relation :locatedAt, :technologyFacilities, :TechnologyFacility
   relation :connectedTo, :technologyDevices, :TechnologyDevice
   relation :composedOf, :technologyDevices, :TechnologyDevice

data/lib/archsight/resources/technology_service.rb

@@ -50,6 +50,13 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
     "servedBy" from ApplicationComponent on its page. An ApplicationService that is `servedBy` the service uses it as a
     whole; list a cluster there only when the service's own components run in it.
 
+    ## Provisioning
+
+    A service that software creates (clusters built by an infrastructure-as-code operator, a database cluster
+    reconciled by a controller) is `provisions`-ed by that `ApplicationComponent`. The relation is written on the
+    component and points down to the service; the service page lists it as incoming "provisions". It says who builds
+    the service, `suppliedBy` says what the service is made of (the system software).
+
     ## Concept and implementation
 
     A service can `specialize` another service (ArchiMate specialization): the general service is the concept, the

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

data/lib/archsight/web/api/docs.rb

@@ -11,8 +11,9 @@ module Archsight::Web::API; end
 module Archsight::Web::API::Docs
   extend Sinatra::Extension
 
+  # A page of its own, not the single page app: ReDoc must not get the app's CSS (Pico restyles every <code>)
   get "/docs/api" do
-    serve_vue
+    send_file File.join(settings.public_folder, "vendor", "redoc", "api.html"), type: :html
   end
 
   # GET /api/v1/docs/resources/:filename — auto-generated resource docs

data/lib/archsight/web/api/openapi/spec.yaml

@@ -623,12 +623,10 @@ paths:
                 type: object
                 properties:
                   html:
-                    type: string
-                    nullable: true
+                    type: [string, "null"]
                     description: '`<figure class="asd-diagram">` with the SVG'
                   error:
-                    type: string
-                    nullable: true
+                    type: [string, "null"]
         '400':
           description: Body is not JSON with a `source` string
           content:
@@ -708,9 +706,11 @@ paths:
       summary: Requirements of a selection of resources
       description: |
         The requirements that the resources selected by `of` realize (`implemented`), partially realize
-        (`partial`) or plan (`planned`), merged over all of them: one entry per requirement with the best status and
-        the resources it comes from (`by`). Sorted by priority (must, should, may, none), then name. `story` is
-        rendered HTML.
+        (`partial`) or plan (`planned`), merged over all of them: one entry per requirement, with the best status
+        any of the resources gives it and the resources it comes from (`by`, each with its own status). Sorted by
+        priority (must, should, may, requirements without a priority last), then name. `story` is rendered HTML.
+        `priority` and `status` filter the merged entries, so `status=partial` lists requirements whose best
+        status is partial.
       operationId: getRequirements
       tags:
         - Search
@@ -725,14 +725,14 @@ paths:
         - name: priority
           in: query
           required: false
-          description: Comma separated list, only requirements with one of these priorities
+          description: Comma separated list, only requirements with one of these priorities (must, should, may)
           schema:
             type: string
           example: must,should
         - name: status
           in: query
           required: false
-          description: Comma separated list, only requirements with one of these statuses
+          description: Comma separated list, only requirements with one of these statuses (implemented, partial, planned)
           schema:
             type: string
           example: implemented,partial
@@ -743,33 +743,42 @@ paths:
             application/json:
               schema:
                 type: object
+                required: [query, total, query_time_ms, requirements]
                 properties:
                   query:
                     type: string
+                    description: The `of` query as given
                   total:
                     type: integer
+                    description: Number of requirements returned
                   query_time_ms:
                     type: number
                   requirements:
                     type: array
                     items:
                       type: object
+                      required: [name, status, priority, story, by]
                       properties:
                         name:
                           type: string
+                          description: Name of the MotivationRequirement
                         status:
                           type: string
                           enum: [implemented, partial, planned]
+                          description: The best status among the resources in `by`
                         priority:
-                          type: string
-                          nullable: true
+                          type: [string, "null"]
+                          enum: [must, should, may, null]
+                          description: Priority of the requirement, null if it has none
                         story:
-                          type: string
-                          nullable: true
+                          type: [string, "null"]
+                          description: The requirement's story as rendered HTML, null if it has none
                         by:
                           type: array
+                          description: The selected resources that realize, partially realize or plan the requirement, best status first
                           items:
                             type: object
+                            required: [kind, name, status]
                             properties:
                               kind:
                                 type: string
@@ -778,12 +787,118 @@ paths:
                               status:
                                 type: string
                                 enum: [implemented, partial, planned]
+                                description: The status this resource gives the requirement
+              example:
+                query: 'ApplicationService: name =~ "Backup"'
+                total: 1
+                query_time_ms: 1.4
+                requirements:
+                  - name: "Requirement:Restore"
+                    status: partial
+                    priority: must
+                    story: "<p>As an operator I can restore a backup.</p>"
+                    by:
+                      - kind: ApplicationService
+                        name: Backup
+                        status: partial
         '400':
-          description: Invalid query, or an unknown priority or status
+          description: |
+            `of` is missing or `priority` or `status` holds an unknown value (`BadRequest`), or `of` is not a valid
+            query (`QueryError`, which also returns the query)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/QueryError'
+                oneOf:
+                  - $ref: '#/components/schemas/Error'
+                  - $ref: '#/components/schemas/QueryError'
+
+  /api/v1/openapi.yaml:
+    get:
+      summary: This OpenAPI document
+      description: |
+        The OpenAPI 3.1 description of this API. The fixed endpoints are written by hand; the schema of every kind
+        (its annotations with type, enum and description, its `spec` and its relations), the list of kinds and the
+        instance detail are generated from the model, so they always describe the kinds this server has.
+      operationId: getOpenApi
+      tags:
+        - Operations
+      responses:
+        '200':
+          description: The OpenAPI document
+          content:
+            text/yaml:
+              schema:
+                type: string
+
+  /maintenance/restart:
+    post:
+      summary: Restart the server
+      description: |
+        Stops the server so that its supervisor (for example a Kubernetes Deployment) starts it again with fresh
+        data. Only available when the server was started with `--enable-restart` (or
+        `ARCHSIGHT_RESTART_ENABLED=true`); otherwise it answers 404. When a restart token is configured it must be
+        sent in the `X-Restart-Token` header.
+      operationId: restart
+      tags:
+        - Operations
+      parameters:
+        - name: X-Restart-Token
+          in: header
+          required: false
+          description: The configured restart token (required when the server has one)
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The server shuts down
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, message]
+                properties:
+                  ok:
+                    type: boolean
+                  message:
+                    type: string
+              example:
+                ok: true
+                message: Server shutting down
+        '401':
+          description: The restart token is missing or wrong
+          content:
+            text/html:
+              schema:
+                type: string
+        '404':
+          description: The restart endpoint is not enabled
+          content:
+            text/html:
+              schema:
+                type: string
+
+  /kinds/{kind}/dot:
+    get:
+      summary: Get the graph of a kind as DOT
+      description: The GraphViz DOT graph of the resources of a kind and the relations between them.
+      operationId: getKindDot
+      tags:
+        - Graph
+      parameters:
+        - $ref: '#/components/parameters/kind'
+      responses:
+        '200':
+          description: GraphViz DOT source
+          content:
+            text/plain:
+              schema:
+                type: string
+        '404':
+          description: Unknown kind
+          content:
+            text/plain:
+              schema:
+                type: string
 
   /dot:
     get:
@@ -1343,13 +1458,11 @@ components:
               items:
                 type: string
         format:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Rendering hint of the annotation (tag_word, tag_list, markdown, link, ...)
           example: tag_word
         type:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Short name of the value type when the annotation declares one (Integer, Float, Time, Person, ...)
           example: Integer
 
@@ -1684,26 +1797,22 @@ components:
       type: object
       properties:
         yaml:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Generated source text, YAML or (for pages) markdown with frontmatter (null if validation failed)
         format:
           type: string
           enum: [yaml, markdown]
           description: Format of `yaml`. Pages (kind Page) are stored as markdown files and replaced as a whole file
         errors:
-          type: array
-          nullable: true
+          type: [array, "null"]
           items:
             type: string
           description: Validation errors (null if valid)
         path_ref:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: "File path reference (edit mode only, e.g., path/file.yaml:5; just the file for markdown pages)"
         content_hash:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Content hash (edit mode only, for optimistic locking)
 
     SaveRequest:

data/lib/archsight/web/api/routes.rb

@@ -7,6 +7,7 @@ require_relative "page_helpers"
 require_relative "requirements_helpers"
 require_relative "analysis_helpers"
 require_relative "../../assets"
+require_relative "../../openapi"
 
 module Archsight; end
 module Archsight::Web; end
@@ -220,8 +221,7 @@ module Archsight::Web::API::Routes
   # GET /api/v1/openapi.yaml - OpenAPI specification
   get "/api/v1/openapi.yaml" do
     content_type "text/yaml"
-    spec_path = File.join(__dir__, "openapi", "spec.yaml")
-    File.read(spec_path)
+    Archsight::OpenAPI.document.to_yaml
   end
 
   # Convenience aliases with .json suffix