OpenAPI description for www.php.net

openapi.yml

openapi: 3.0.4
info:
    title: PHP Website API
    description: APIs available for use on the www.php.net website.
    version: 2025.4.1

servers:
    - url: https://www.php.net
      description: The php.net website.

paths:
    "/mirror-info.php":
        get:
            summary: >-
                Returns information about the host running php.net.
                Historically, this was unique per mirror.
                With the move to a CDN model in 2019, there is now only one canonical source, and thus only one relevant configuration.
            responses:
                "200":
                    description: Successful response of host configuration. This API does not error.
                    content:
                        "text/plain":
                            schema:
                                readOnly: true
                                externalDocs:
                                    description: This pipe delimited string's contents are described in the source code for this file.
                                    url: https://github.com/php/web-php/blob/master/mirror-info.php
                                example: "https://www.php.net/|8.4.5|1743832640|0|0|en|manual-noalias|1|Core,date,libxml,json,SPL,Zend OPcache|php-web4|169.254.12.255"

    "/releases/feed.php":
        get:
            summary: Atom feed of php.net news and announcements.
            responses:
                "200":
                    description: Atom feed of php.net news and announcements.
                    content:
                        "application/atom+xml":
                            schema:
                                readOnly: true
                                externalDocs:
                                    description: Standard Atom feed with additional fields in the php: xml namespace.
                                    url: http://php.net/ns/releases

    # Alias of /releases/feed.php
    "/relases.atom":
        "$ref": "#/releases/feed.php"

    # See inline notes, the major/minor versions are variable.
    # Right now, I'm thinking openapi.yml might need to be dynamically generated. :(
    "/releases/states.php":
        get:
            summary: Currently active versions of PHP.
            responses:
                "200":
                    description: Actively supported per-branch versions of PHP.
                    content:
                        "application/json":
                            schema:
                                type: object
                                properties:
                                   "8": # This field name will increase over time and may coexist with other major versions.
                                        type: object
                                        properties:
                                            "8.4": # This field name will increase over time and will coexist with other minor versions.
                                                type: object
                                                properties:
                                                    state:
                                                        description: Overall release readiness of the branch.
                                                        type: string
                                                        oneOf:
                                                            - stable
                                                            - security
                                                            - eol
                                                            - future
                                                    initial_release:
                                                        description: Date on which first GA release of the branch was announced.
                                                        type: date-time
                                                    active_support_end:
                                                        description: Date on which general bugfix support for this branch ends.
                                                        type: date-time
                                                    security_support_end:
                                                        description: Date on which all support for this branch ends.
                                                        type: date-time

This looks useful! I am not sure how many tools correctly use the externalDocs information, maybe it would be better (but less elegant!) to include the information and the links in the descriptions (description fields support markdown).

For validation, try Vacuum with a config.yml file like:

extends: [[spectral:oas, off]]
rules:
 oas3-schema: true

Command then goes: vacuum lint -r config.yml -d openapi.yml

Line 41 needs quotes because YAML

The $ref bits don't work quite like you might expect. I suggest that you update to OpenAPI 3.1.x and put a PathItem into a components section and $ref to that ... here's a snippet:

    "/releases/feed.php":
        "$ref": "#/components/pathItems/releases"

    # Alias of /releases/feed.php
    "/relases.atom":
        "$ref": "#/components/pathItems/releases"

components:
    pathItems:
        releases:
            get:
                summary: Atom feed of php.net news and announcements.
                responses:
                    "200":
                        description: Atom feed of php.net news and announcements.
                        content:
                            "application/atom+xml":
                                schema:
                                    readOnly: true
                                    externalDocs:
                                        description: "Standard Atom feed with additional fields in the php: xml namespace."
                                        url: http://php.net/ns/releases