API /hardware endpoint: eol field spec vs. actual response inconsistency

[schnoddelbotz]

According to https://snipe-it.readme.io/reference/hardware-list , a GET /hardware 200-OK API response is supposed to contain an eol object. But the actual eol field in the response (e.g. from using "Try it!" on that page) is a plain string -- see attached screenshot; here: "12 months".

I was using oapi-codegen against the snipe openapi specs and all worked fine until I stumbled upon a record that had a non-null eol. Obviously I'd like to avoid patching the autogenerated code ... all specs (v6, v7, v8) seem to be affected.

[welcome]

👋 Thanks for opening your first issue here! If you're reporting a 🐞 bug, please make sure you include steps to reproduce it. We get a lot of issues on this repo, so please be patient and we will get back to you as soon as we can.

[schnoddelbotz]

👀 looking at it again... it seems asset_eol_date field has documented EOL OBJECT type in the response ... but is completely 'undocumented'. Feels it was somehow confused with eol?

[snipe]

eol is the EOL rate on the model, as opposed to the asset_eol_date which is on the asset as an available override, in case a specific asset has a different EOL date than the one we'd expect for the asset model.

{
    "id": 1,
    "name": "",
    "asset_tag": "1156325115",
    "serial": "d22b86a9-3ff4-369d-a8b2-3e90293ac71f",
    "model": {
        "id": 1,
        "name": "Macbook Pro 13""
    },
    "byod": false,
    "requestable": true,
    "model_number": "5468760902585226",
    "eol": "36 months",
    "asset_eol_date": {
        "date": "2027-07-29",
        "formatted": "Thu Jul 29, 2027"
    },
    "status_label": {
        "id": 1,
        "name": "Ready to Deploy",
        "status_type": "deployable",
        "status_meta": "deployable"
    },
    "category": {
        "id": 1,
        "name": "Laptops"
    },
    "manufacturer": null,
    "supplier": {
        "id": 5,
        "name": "Hand, Cummerata and Kohler"
    },
    "notes": "Created by DB seeder",
    "order_number": "24556396",
    "company": null,
    "location": {
        "id": 2,
        "name": "East Adrain"
    },
    "rtd_location": {
        "id": 2,
        "name": "East Adrain"
    },
    "image": "https://snipe-it.test/uploads/models/mbp.jpg",
    "qr": null,
    "alt_barcode": "https://snipe-it.test/uploads/barcodes/-1156325115.png",
    "assigned_to": null,
    "warranty_months": null,
    "warranty_expires": null,
    "created_by": {
        "id": 1,
        "name": "Admin User"
    },
    "created_at": {
        "datetime": "2025-04-22 18:10:53",
        "formatted": "Tue Apr 22, 2025 6:10PM"
    },
    "updated_at": {
        "datetime": "2025-04-22 18:12:11",
        "formatted": "Tue Apr 22, 2025 6:12PM"
    },
    "last_audit_date": null,
    "next_audit_date": null,
    "deleted_at": null,
    "purchase_date": {
        "date": "2024-07-29",
        "formatted": "Mon Jul 29, 2024"
    },
    "age": "9 months ago",
    "last_checkout": null,
    "last_checkin": null,
    "expected_checkin": null,
    "purchase_cost": "971.74",
    "checkin_counter": 0,
    "checkout_counter": 0,
    "requests_counter": 0,
    "user_can_checkout": true,
    "book_value": "728.81",
    "custom_fields": {},
    "available_actions": {
        "checkout": true,
        "checkin": true,
        "clone": true,
        "restore": false,
        "update": true,
        "audit": true,
        "delete": true
    }
}

In the assets transformer, we try to give you a calculated date IF we have enough information, and we provide the object if we have an explicit date set as asset_eol_date.

snipe-it/app/Http/Transformers/AssetsTransformer.php

Lines 45 to 46 in 049a669

	'eol' => (($asset->asset_eol_date != '') && ($asset->purchase_date != '')) ? (int) Carbon::parse($asset->asset_eol_date)->diffInMonths($asset->purchase_date, true) . ' months' : null,
	'asset_eol_date' => ($asset->asset_eol_date != '') ? Helper::getFormattedDateObject($asset->asset_eol_date, 'date') : null,

[schnoddelbotz]

Thanks. The example response you provided and the code look ok so far - I believe only the openapi spec files are wrong:
Looking at https://snipe-it.readme.io/openapi/6810cca3d9406800127aec55 , the 200 API response for /hardware has this in its schema section:

  "eol": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "example": "2023-09-16"
      },
      "formatted": {
        "type": "string",
        "example": "Sat Sep 16, 2023"
      }
    }
  },

There is a) no mention of asset_eol_date at all on the /hardware endpoint spec and b) the eol field shown above should be of string type ("n months"), not the object type really belonging to asset_eol_date -- no?

The Go code generated by oapi-codegen based on the snipe openapi spec currently expects eol in a GET /hardware response to be of the object type shown above -- and thus logically fails to unmarshal the actual "n months" string response into the expected object type.

Just as a side note, I was wondering whether API consumers might prefer the eol field's unit (i.e. months) to be documented and getting the (integer) value only - potentially easing working with that data (+ i18n) ...?

[snipe]

I'm not actually sure how Readme.io generates those docs. :(