Fix GraphQL docstrings

Oops, right, I forgot for a while that GraphQL fields have a special syntax for docstrings, and it's not just comments! This will help stuff show up in our GraphQL Playground API docs correctly 🥰
This commit is contained in:
Emi Matchu 2021-05-27 16:36:43 -07:00
parent abc322c24d
commit 8525ac393f
7 changed files with 144 additions and 89 deletions

View file

@ -17,12 +17,14 @@ const typeDefs = gql`
# Cache for 1 week (unlikely to change)
type AppearanceLayer @cacheControl(maxAge: 604800) {
# The DTI ID. Guaranteed unique across all layers of all types.
"The DTI ID. Guaranteed unique across all layers of all types."
id: ID!
# The Neopets ID. Guaranteed unique across layers of the _same_ type, but
# not of different types. That is, it's allowed and common for an item
# layer and a pet layer to have the same remoteId.
"""
The Neopets ID. Guaranteed unique across layers of the _same_ type, but
not of different types. That is, it's allowed and common for an item
layer and a pet layer to have the same remoteId.
"""
remoteId: ID!
zone: Zone!

View file

@ -12,10 +12,15 @@ const typeDefs = gql`
id: ID!
name: String
# A user-customized description. May contain Markdown and limited HTML.
"""
A user-customized description. May contain Markdown and limited HTML.
WARNING: If you're using this in an application, you MUST ensure that the
content is rendered safely! Do not render this as HTML unless you
are confident that you've sanitized it appropriately.
"""
description: String
# Whether this is a list of items they own, or items they want.
"Whether this is a list of items they own, or items they want."
ownsOrWantsItems: OwnsOrWants!
# Each user has a "default list" of items they own/want. When users click
@ -30,8 +35,10 @@ const typeDefs = gql`
}
extend type Mutation {
# Edit the metadata of a closet list. Requires the current user to own the
# list, or for the correct supportSecret to be provided.
"""
Edit the metadata of a closet list. Requires the current user to own the
list, or for the correct supportSecret to be provided.
"""
editClosetList(
closetListId: ID!
name: String!

View file

@ -15,101 +15,129 @@ const typeDefs = gql`
thumbnailUrl: String!
rarityIndex: Int!
# Whether this item comes from the NC Mall.
"Whether this item comes from the NC Mall."
isNc: Boolean!
# Whether this item comes from a paintbrush.
"Whether this item comes from a paintbrush."
isPb: Boolean!
# When this item was first added to DTI. ISO 8601 string, or null if the
# item was added so long ago that we don't have this field!
"""
When this item was first added to DTI. ISO 8601 string, or null if the
item was added so long ago that we don't have this field!
"""
createdAt: String
# This item's capsule trade value as text, according to wakaguide.com, as a
# human-readable string. Will be null if the value is not known, or if
# there's an error connecting to the data source.
"""
This item's capsule trade value as text, according to wakaguide.com, as a
human-readable string. Will be null if the value is not known, or if
there's an error connecting to the data source.
"""
wakaValueText: String @cacheControl(maxAge: ${oneHour})
currentUserOwnsThis: Boolean! @cacheControl(scope: PRIVATE)
currentUserWantsThis: Boolean! @cacheControl(scope: PRIVATE)
# How many users are offering/seeking this in their public trade lists.
# Excludes users that seem relatively inactive.
"""
How many users are offering/seeking this in their public trade lists.
Excludes users that seem relatively inactive.
"""
numUsersOfferingThis: Int! @cacheControl(maxAge: ${oneHour})
numUsersSeekingThis: Int! @cacheControl(maxAge: ${oneHour})
# The trades available for this item, grouped by offering vs seeking.
"The trades available for this item, grouped by offering vs seeking."
tradesOffering: [ItemTrade!]! @cacheControl(maxAge: 0)
tradesSeeking: [ItemTrade!]! @cacheControl(maxAge: 0)
# How this item appears on the given species/color combo. If it does not
# fit the pet, we'll return an empty ItemAppearance with no layers.
"""
How this item appears on the given species/color combo. If it does not
fit the pet, we'll return an empty ItemAppearance with no layers.
"""
appearanceOn(speciesId: ID!, colorId: ID!): ItemAppearance! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay})
# This is set manually by Support users, when the pet is only for e.g.
# Maraquan pets, and our usual auto-detection isn't working. We provide
# this for the Support UI; it's not very helpful for most users, because it
# can be empty even if the item _has_ an auto-detected special color.
"""
This is set manually by Support users, when the pet is only for e.g.
Maraquan pets, and our usual auto-detection isn't working. We provide
this for the Support UI; it's not very helpful for most users, because it
can be empty even if the item _has_ an auto-detected special color.
"""
manualSpecialColor: Color @cacheControl(maxAge: 0)
# This is set manually by Support users, when the item _seems_ to fit all
# pets the same because of its zones, but it actually doesn't - e.g.,
# the Dug Up Dirt Foreground actually looks different for each body. We
# provide this for the Support UI; it's not very helpful for most users,
# because it's only used at modeling time. This value does not change how
# layer data from this API should be interpreted!
"""
This is set manually by Support users, when the item _seems_ to fit all
pets the same because of its zones, but it actually doesn't - e.g.,
the Dug Up Dirt Foreground actually looks different for each body. We
provide this for the Support UI; it's not very helpful for most users,
because it's only used at modeling time. This value does not change how
layer data from this API should be interpreted!
"""
explicitlyBodySpecific: Boolean! @cacheControl(maxAge: 0)
# This is set manually by Support users, when the item is from the NC Mall
# but isn't correctly labeled as r500 on Neopets.com. When this is true,
# it sets isNc to be true as well, regardless of rarityIndex.
"""
This is set manually by Support users, when the item is from the NC Mall
but isn't correctly labeled as r500 on Neopets.com. When this is true,
it sets isNc to be true as well, regardless of rarityIndex.
"""
isManuallyNc: Boolean!
# Get the species that we need modeled for this item for the given color.
#
# NOTE: Most color IDs won't be accepted here. Either pass the ID of a
# major special color like Baby (#6), or leave it blank for standard
# bodies like Blue, Green, Red, etc.
"""
Get the species that we need modeled for this item for the given color.
NOTE: Most color IDs won't be accepted here. Either pass the ID of a
major special color like Baby (#6), or leave it blank for standard
bodies like Blue, Green, Red, etc.
"""
speciesThatNeedModels(colorId: ID): [Species!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneHour})
# Return a single ItemAppearance for this item. It'll be for the species
# with the smallest ID for which we have item appearance data, and a basic
# color. We use this on the item page, to initialize the preview section.
# (You can find out which species this is for by going through the body
# field on ItemAppearance!)
#
# There's also optional fields preferredSpeciesId and preferredColorId, to
# request a certain species or color if possible. We'll try to match each,
# with precedence to species first; then fall back to the canonical values.
#
# Note that the exact choice of color doesn't usually affect this field,
# because ItemAppearance is per-body rather than per-color. It's most
# relevant for special colors like Baby or Mutant. But the
# canonicalAppearance on the Body type _does_ use the preferred color more
# precisely!
"""
Return a single ItemAppearance for this item. It'll be for the species
with the smallest ID for which we have item appearance data, and a basic
color. We use this on the item page, to initialize the preview section.
(You can find out which species this is for by going through the body
field on ItemAppearance!)
There's also optional fields preferredSpeciesId and preferredColorId, to
request a certain species or color if possible. We'll try to match each,
with precedence to species first; then fall back to the canonical values.
Note that the exact choice of color doesn't usually affect this field,
because ItemAppearance is per-body rather than per-color. It's most
relevant for special colors like Baby or Mutant. But the
canonicalAppearance on the Body type _does_ use the preferred color more
precisely!
"""
canonicalAppearance(preferredSpeciesId: ID, preferredColorId: ID): ItemAppearance @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
# All zones that this item occupies, for at least one body. That is, it's
# a union of zones for all of its appearances! We use this for overview
# info about the item.
"""
All zones that this item occupies, for at least one body. That is, it's
a union of zones for all of its appearances! We use this for overview
info about the item.
"""
allOccupiedZones: [Zone!]! @cacheControl(maxAge: ${oneHour})
# The zones this item restricts. Turns out, even though we offer this on
# ItemAppearance for consistency, this is static across all appearances.
"""
The zones this item restricts. Turns out, even though we offer this on
ItemAppearance for consistency, this is static across all appearances.
"""
restrictedZones: [Zone!]! @cacheControl(maxAge: ${oneHour}, staleWhileRevalidate: ${oneWeek})
# All bodies that this item is compatible with. Note that this might return
# the special representsAllPets body, e.g. if this is just a Background!
# Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones.
"""
All bodies that this item is compatible with. Note that this might return
the special representsAllPets body, e.g. if this is just a Background!
Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones.
"""
compatibleBodies: [Body!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
# All bodies that this item is compatible with, and the zones this item
# occupies for that body. Note that this might return the special
# representsAllPets body, e.g. if this is just a Background!
"""
All bodies that this item is compatible with, and the zones this item
occupies for that body. Note that this might return the special
representsAllPets body, e.g. if this is just a Background!
"""
compatibleBodiesAndTheirZones: [BodyAndZones!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
# All appearances for this item. Used in Support tools, to show and manage
# how this item fits every pet body.
"""
All appearances for this item. Used in Support tools, to show and manage
how this item fits every pet body.
"""
allAppearances: [ItemAppearance!]!
}

View file

@ -16,14 +16,16 @@ const typeDefs = gql`
closetedItems: [Item!]!
creator: User
# When this outfit was created. ISO 8601 string.
"When this outfit was created. ISO 8601 string."
createdAt: String!
# When this outfit was last updated. ISO 8601 string.
"When this outfit was last updated. ISO 8601 string."
updatedAt: String!
# This is a convenience field: you could query this from the combination of
# petAppearance and wornItems, but this gets you it in one shot!
"""
This is a convenience field: you could query this from the combination of
petAppearance and wornItems, but this gets you it in one shot!
"""
itemAppearances: [ItemAppearance!]!
}
@ -34,8 +36,10 @@ const typeDefs = gql`
extend type Mutation {
saveOutfit(
id: ID # Optional, is null when saving new outfits.
name: String # Optional, server may fill in a placeholder.
"Optional, is null when saving new outfits."
id: ID
"Optional, server may fill in a placeholder."
name: String
speciesId: ID!
colorId: ID!
pose: Pose!

View file

@ -11,10 +11,14 @@ const typeDefs = gql`
petAppearance: PetAppearance!
wornItems: [Item!]!
species: Species! # to be deprecated? can use petAppearance? 🤔
color: Color! # to be deprecated? can use petAppearance? 🤔
pose: Pose! # to be deprecated? can use petAppearance? 🤔
items: [Item!]! # deprecated alias for wornItems
"to be deprecated? can use petAppearance? 🤔"
species: Species!
"to be deprecated? can use petAppearance? 🤔"
color: Color!
"to be deprecated? can use petAppearance? 🤔"
pose: Pose!
"deprecated alias for wornItems"
items: [Item!]!
}
extend type Query {

View file

@ -16,7 +16,7 @@ const typeDefs = gql`
name: String!
isStandard: Boolean!
# All SpeciesColorPairs of this color.
"All SpeciesColorPairs of this color."
appliedToAllCompatibleSpecies: [SpeciesColorPair!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay})
}
@ -24,13 +24,17 @@ const typeDefs = gql`
id: ID!
name: String!
# A PetAppearance that has this species. Prefers Blue (or the optional
# preferredColorId), and happy poses.
"""
A PetAppearance that has this species. Prefers Blue (or the optional
preferredColorId), and happy poses.
"""
canonicalAppearance(preferredColorId: ID): PetAppearance
# The bodyId for PetAppearances that use this species and a standard color.
# We use this to preload the standard body IDs, so that items stay when
# switching between standard colors.
"""
The bodyId for PetAppearances that use this species and a standard color.
We use this to preload the standard body IDs, so that items stay when
switching between standard colors.
"""
standardBodyId: ID!
}

View file

@ -13,20 +13,26 @@ const typeDefs = gql`
itemsTheyOwn: [Item!]!
itemsTheyWant: [Item!]!
# These items represent potential trade matches. We use this as a preview
# in the trade list table.
"""
These items represent potential trade matches. We use this as a preview
in the trade list table.
"""
itemsTheyOwnThatCurrentUserWants: [Item!]!
itemsTheyWantThatCurrentUserOwns: [Item!]!
# When this user last updated any of their trade lists, as an ISO 8601
# timestamp.
"""
When this user last updated any of their trade lists, as an ISO 8601
timestamp.
"""
lastTradeActivity: String!
# This user's outfits. Returns an empty list if the current user is not
# authorized to see them.
"""
This user's outfits. Returns an empty list if the current user is not
authorized to see them.
"""
outfits: [Outfit!]!
# This user's email address. Requires the correct supportSecret to view.
"This user's email address. Requires the correct supportSecret to view."
emailForSupportUsers(supportSecret: String!): String!
}