json-api/content-type
Since 0.0.1 · fixed by --fix · In the rulesets: JsonApi at error
This rule checks that every request body and response of the document declares the
application/vnd.api+json media type.
Rule details
JSON:API clients and servers negotiate with the application/vnd.api+json media type; a document
that declares application/json describes the same bytes, but hides that the API follows JSON:API
from the tools that read it, and from the clients that send the Accept and Content-Type
headers the specification requires.
The rule reports Request body media type is not application/vnd.api+json and
Response media type is not application/vnd.api+json. It is part of the json-api ruleset and
meant for APIs that follow JSON:API; turn it off for the others.
Examples
Good. The response says it is a JSON:API document.
openapi: 3.1.0
info:
title: Users
version: 1.0.0
paths:
/users:
get:
responses:
"200":
description: A list of users.
content:
application/vnd.api+json:
schema:
$ref: "#/components/schemas/UserListResponse"
Bad. A JSON:API document declared as plain JSON.
openapi: 3.1.0
info:
title: Users
version: 1.0.0
paths:
/users:
get:
responses:
"200":
description: A list of users.
content:
application/json:
schema:
$ref: "#/components/schemas/UserListResponse"
Automatic fixes
--fix renames a content entry that is the only one and is application/json to
application/vnd.api+json, keeping the rest of the media type. A content map with several
entries is left for you to decide.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
json-api/content-type: off