Does Backstage expose an endpoint for accessing the published OpenAPI spec for a given API?

Question

For a casual user of Backstage, it is not immediately obvious how you can access a published API spec in its raw (non-HTML rendered) form. I tried clicking around, but I found no obvious solution that would just render the spec as plain text. The closest thing was the Definition -> Raw option, but that could not be used as part of a pipeline using curl without parsing HTML ...

Any way I can access the raw yaml spec?

Answer 1

Got it after some experimentation trying to find the base API url and some fiddling with the docs:

'https://my-api-catalog.server.dev/api/catalog/entities/by-query?filter=kind=API,metadata.name=my-api' 

This would serve the YAML spec definition, encoded as JSON. Maybe there is a way of achieving this in a simpler way (please post a better version :)), but I did it like this in my script:

fetch_spec(){
    NAME="$1"
    curl -s -H 'Accept: application/json' \
        "https://my-api-catalog.server.dev/api/catalog/entities/by-query?filter=kind=API,metadata.name=$NAME" \
        | jq '.items[0].spec.definition' > .tmp.result.json

    # Get rid of embedded newlines
    node -r 'fs' -p 'JSON.parse(fs.readFileSync("./.tmp.result.json").toString())' \
        > ./specs/$NAME.spec.yaml
    rm .tmp.result.json
}

fetch my-api # results in specs/my-api.spec.yaml being written