From 677482ffcba3bfd3e65f4343d3662275c394471e Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Sat, 4 Oct 2025 21:33:55 +0200 Subject: [PATCH] Improved the definition of the schema types for the OpenAPI specification in the library target. --- Sources/MarvelService/openapi.yaml | 1676 ++++++++++++++++------------ 1 file changed, 991 insertions(+), 685 deletions(-) diff --git a/Sources/MarvelService/openapi.yaml b/Sources/MarvelService/openapi.yaml index 1da5d1c5..6a18db9a 100644 --- a/Sources/MarvelService/openapi.yaml +++ b/Sources/MarvelService/openapi.yaml @@ -138,12 +138,18 @@ paths: application/json: schema: $ref: '#/components/schemas/CharacterDataWrapper' + "404": + description: Not Found response + content: + application/json: + schema: + $ref: '#/components/schemas/StandardError' "409": description: Conflict response content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/characters/{characterId}: get: tags: @@ -171,7 +177,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/characters/{characterId}/comics: get: tags: @@ -400,7 +406,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/characters/{characterId}/events: get: tags: @@ -516,7 +522,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/characters/{characterId}/series: get: tags: @@ -654,7 +660,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/characters/{characterId}/stories: get: tags: @@ -757,7 +763,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics: get: tags: @@ -990,7 +996,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics/{comicId}: get: tags: @@ -1018,7 +1024,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics/{comicId}/characters: get: tags: @@ -1122,7 +1128,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics/{comicId}/creators: get: tags: @@ -1262,7 +1268,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics/{comicId}/events: get: tags: @@ -1377,7 +1383,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/comics/{comicId}/stories: get: tags: @@ -1480,7 +1486,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators: get: tags: @@ -1624,7 +1630,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators/{creatorId}: get: tags: @@ -1652,7 +1658,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators/{creatorId}/comics: get: tags: @@ -1885,7 +1891,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators/{creatorId}/events: get: tags: @@ -2000,7 +2006,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators/{creatorId}/series: get: tags: @@ -2138,7 +2144,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/creators/{creatorId}/stories: get: tags: @@ -2241,7 +2247,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events: get: tags: @@ -2360,7 +2366,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}: get: tags: @@ -2388,7 +2394,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}/characters: get: tags: @@ -2492,7 +2498,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}/comics: get: tags: @@ -2744,7 +2750,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}/creators: get: tags: @@ -2884,7 +2890,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}/series: get: tags: @@ -3022,7 +3028,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/events/{eventId}/stories: get: tags: @@ -3125,7 +3131,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series: get: tags: @@ -3267,7 +3273,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}: get: tags: @@ -3295,7 +3301,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}/characters: get: tags: @@ -3399,7 +3405,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}/comics: get: tags: @@ -3640,7 +3646,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}/creators: get: tags: @@ -3780,7 +3786,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}/events: get: tags: @@ -3895,7 +3901,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/series/{seriesId}/stories: get: tags: @@ -3998,7 +4004,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories: get: tags: @@ -4105,7 +4111,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}: get: tags: @@ -4133,7 +4139,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}/characters: get: tags: @@ -4237,7 +4243,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}/comics: get: tags: @@ -4478,7 +4484,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}/creators: get: tags: @@ -4618,7 +4624,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}/events: get: tags: @@ -4733,7 +4739,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' /v1/public/stories/{storyId}/series: get: tags: @@ -4871,311 +4877,208 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ErrorResponse' + $ref: '#/components/schemas/StandardError' components: schemas: - ComicList: +# Core Entity Representations + Character: type: object + description: A character resource type that represents the women, men, organizations, alien species, deities, animals, non-corporeal entities, trans-dimensional manifestations, abstract personifications, and green amorphous blobs which occupy the Marvel Universe as well as various alternate universes, timelines and altered realities therein (e.g. Spider-Man). properties: - available: + id: type: integer - description: The number of total available issues in this list. Will always - be greater than or equal to the "returned" value. + description: The unique ID of the character resource. format: int32 - returned: - type: integer - description: The number of issues returned in this collection (up to 20). - format: int32 - collectionURI: + name: type: string - description: The path to the full list of issues in this collection. - items: + description: The name of the character. + description: + type: string + description: A short bio or description of the character. + modified: + type: string + description: The date the resource was most recently modified. + format: date + resourceURI: + type: string + description: The canonical URL identifier for this resource. + urls: type: array - description: The list of returned issues in this collection. + description: A set of public web site URLs for the resource. + items: + $ref: '#/components/schemas/Url' + thumbnail: + description: The representative image for this character. + $ref: '#/components/schemas/Image' + comics: + description: A resource list containing comics which feature this character. + $ref: '#/components/schemas/ComicList' + stories: + description: A resource list containing stories which this character appears. + $ref: '#/components/schemas/StoryList' + events: + description: A resource list containing events which this character appears. + $ref: '#/components/schemas/EventList' + series: + description: A resource list containing series in which this character appears. + $ref: '#/components/schemas/SeriesList' + required: + - id + - name + - description + - modified + - resourceURI + - urls + - thumbnail + - comics + - stories + - events + - series + Comic: + type: object + description: A comic book resource type that represents physical or digital products that end-users read. This definition includes individual print and digital comic issues, collections and graphic novels (e.g. Amazing Fantasy \#15). + properties: + id: + type: integer + description: The unique ID of the comic resource. + format: int32 + digitalId: + type: integer + description: The ID of the digital comic representation of this comic. Will be 0 if the comic is not available digitally. + format: int32 + title: + type: string + description: The canonical title of the comic. + issueNumber: + type: number + description: The number of the issue in the series (will generally be 0 for collection formats). + format: double + variantDescription: + type: string + description: If the issue is a variant (e.g. an alternate cover, second printing, or director\'s cut), a text description of the variant. + description: + type: string + description: The preferred description of the comic. + modified: + type: string + description: The date the resource was most recently modified. + format: date + isbn: + type: string + description: The ISBN for the comic (generally only populated for collection formats). + upc: + type: string + description: The UPC barcode number for the comic (generally only populated for periodical formats). + diamondCode: + type: string + description: The Diamond code for the comic. + ean: + type: string + description: The EAN barcode for the comic. + issn: + type: string + description: The ISSN barcode for the comic. + format: + type: string + description: The publication format of the comic (e.g. comic, hardcover, trade paperback). + pageCount: + type: integer + description: The number of story pages in the comic. + format: int32 + textObjects: + type: array + description: A set of descriptive text blurbs for the comic. + items: + $ref: '#/components/schemas/TextObject' + resourceURI: + type: string + description: The canonical URL identifier for this resource. + urls: + type: array + description: A set of public web site URLs for the resource. + items: + $ref: '#/components/schemas/Url' + series: + description: A summary representation of the series to which this comic belongs. + $ref: '#/components/schemas/SeriesSummary' + variants: + type: array + description: A list of variant issues for this comic (includes the "original" issue if the current issue is a variant). items: $ref: '#/components/schemas/ComicSummary' - EventList: - type: object - properties: - available: - type: integer - description: The number of total available events in this list. Will always - be greater than or equal to the "returned" value. - format: int32 - returned: - type: integer - description: The number of events returned in this collection (up to 20). - format: int32 - collectionURI: - type: string - description: The path to the full list of events in this collection. - items: + collections: type: array - description: The list of returned events in this collection. + description: A list of collections which include this comic (will generally be empty if the comic's format is a collection). items: - $ref: '#/components/schemas/EventSummary' - CreatorList: - type: object - properties: - available: - type: integer - description: The number of total available creators in this list. Will always - be greater than or equal to the "returned" value. - format: int32 - returned: - type: integer - description: The number of creators returned in this collection (up to 20). - format: int32 - collectionURI: - type: string - description: The path to the full list of creators in this collection. - items: + $ref: '#/components/schemas/ComicSummary' + collectedIssues: type: array - description: The list of returned creators in this collection. + description: A list of issues collected in this comic (will generally be empty for periodical formats such as "comic" or "magazine"). items: - $ref: '#/components/schemas/CreatorSummary' - CharacterList: - type: object - properties: - available: - type: integer - description: The number of total available characters in this list. Will - always be greater than or equal to the "returned" value. - format: int32 - returned: - type: integer - description: The number of characters returned in this collection (up to - 20). - format: int32 - collectionURI: - type: string - description: The path to the full list of characters in this collection. - items: + $ref: '#/components/schemas/ComicSummary' + dates: type: array - description: The list of returned characters in this collection. + description: A list of key dates for this comic. items: - $ref: '#/components/schemas/CharacterSummary' - SeriesList: - type: object - properties: - available: - type: integer - description: The number of total available series in this list. Will always - be greater than or equal to the "returned" value. - format: int32 - returned: - type: integer - description: The number of series returned in this collection (up to 20). - format: int32 - collectionURI: - type: string - description: The path to the full list of series in this collection. - items: + $ref: '#/components/schemas/ComicDate' + prices: type: array - description: The list of returned series in this collection. + description: A list of prices for this comic. items: - $ref: '#/components/schemas/SeriesSummary' - StoryList: - type: object - properties: - available: - type: integer - description: The number of total available stories in this list. Will always - be greater than or equal to the "returned" value. - format: int32 - returned: - type: integer - description: The number of stories returned in this collection (up to 20). - format: int32 - collectionURI: - type: string - description: The path to the full list of stories in this collection. - items: + $ref: '#/components/schemas/ComicPrice' + thumbnail: + description: The representative image for this comic. + $ref: '#/components/schemas/Image' + images: type: array - description: The list of returned stories in this collection. + description: A list of promotional images associated with this comic. items: - $ref: '#/components/schemas/StorySummary' - CharacterSummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual character resource. - name: - type: string - description: The full name of the character. - role: - type: string - description: The role of the creator in the parent entity. - EventSummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual event resource. - name: - type: string - description: The name of the event. - SeriesSummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual series resource. - name: - type: string - description: The canonical name of the series. - ComicSummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual comic resource. - name: - type: string - description: The canonical name of the comic. - Url: - type: object - properties: - type: - type: string - description: A text identifier for the URL. - url: - type: string - description: "A full URL (including scheme, domain, and path)." - CreatorSummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual creator resource. - name: - type: string - description: The full name of the creator. - role: - type: string - description: The role of the creator in the parent entity. - StorySummary: - type: object - properties: - resourceURI: - type: string - description: The path to the individual story resource. - name: - type: string - description: The canonical name of the story. - type: - type: string - description: The type of the story (interior or cover). - Image: - type: object - properties: - path: - type: string - description: The directory path of to the image. - extension: - type: string - description: The file extension for the image. - ComicDate: - type: object - properties: - type: - type: string - description: "A description of the date (e.g. onsale date, FOC date)." - date: - type: string - description: The date. - format: date - CharacterDataContainer: - type: object - properties: - offset: - type: integer - description: The requested offset (number of skipped results) of the call. - format: int32 - limit: - type: integer - description: The requested result limit. - format: int32 - total: - type: integer - description: The total number of resources available given the current filter - set. - format: int32 - count: - type: integer - description: The total number of results returned by this call. - format: int32 - results: - type: array - description: The list of characters returned by the call. - items: - $ref: '#/components/schemas/Character' - EventDataContainer: - type: object - properties: - offset: - type: integer - description: The requested offset (number of skipped results) of the call. - format: int32 - limit: - type: integer - description: The requested result limit. - format: int32 - total: - type: integer - description: The total number of resources available given the current filter - set. - format: int32 - count: - type: integer - description: The total number of results returned by this call. - format: int32 - results: - type: array - description: The list of events returned by the call - items: - $ref: '#/components/schemas/Event' - ComicPrice: - type: object - properties: - type: - type: string - description: "A description of the price (e.g. print price, digital price)." - price: - type: number - description: The price (all prices in USD). - format: float - EventDataWrapper: - type: object - properties: - code: - type: integer - description: The HTTP status code of the returned result. - format: int32 - status: - type: string - description: A string description of the call status. - copyright: - type: string - description: The copyright notice for the returned result. - attributionText: - type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: - type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/EventDataContainer' - etag: - type: string - description: A digest value of the content returned by the call. + $ref: '#/components/schemas/Image' + creators: + description: A resource list containing creators associated with this comic. + $ref: '#/components/schemas/CreatorList' + characters: + description: A resource list containing characters which appear in this comic. + $ref: '#/components/schemas/CharacterList' + stories: + description: A resource list containing stories which appear in this comic. + $ref: '#/components/schemas/StoryList' + events: + description: A resource list containing events which this comic appears. + $ref: '#/components/schemas/EventList' + required: + - id + - digitalId + - title + - issueNumber + - variantDescription + - description + - modified + - isbn + - upc + - diamondCode + - ean + - issn + - format + - pageCount + - textObjects + - resourceURI + - urls + - series + - variants + - collections + - collectedIssues + - dates + - prices + - thumbnail + - images + - creators + - characters + - stories + - events Creator: type: object + description: A creator resource type that represents women, men and organizations who create comics (e.g. Jack Kirby). They are assigned to the specific comic stories on which they worked, but we bubble up those assignments to the issues, series and events in which the stories appear as a convenience. properties: id: type: integer @@ -5195,8 +5098,7 @@ components: description: The suffix or honorific for the creator. fullName: type: string - description: The full name of the creator (a space-separated concatenation - of the above four fields). + description: The full name of the creator (a space-separated concatenation of the above four fields). modified: type: string description: The date the resource was most recently modified. @@ -5210,17 +5112,38 @@ components: items: $ref: '#/components/schemas/Url' thumbnail: + description: The representative image for this creator. $ref: '#/components/schemas/Image' series: + description: A resource list containing series which feature work by this creator. $ref: '#/components/schemas/SeriesList' stories: + description: A resource list containing stories which feature work by this creator. $ref: '#/components/schemas/StoryList' comics: + description: A resource list containing comics which feature work by this creator. $ref: '#/components/schemas/ComicList' events: + description: A resource list containing events which feature work by this creator. $ref: '#/components/schemas/EventList' + required: + - id + - firstName + - middleName + - lastName + - suffix + - fullName + - modified + - resourceURI + - urls + - thumbnail + - series + - stories + - comics + - events Event: type: object + description: An event resource type that represents big, universe-altering storylines (e.g. Infinity). A comic's appearance in an event is often independent of its membership in a series. properties: id: type: integer @@ -5253,209 +5176,49 @@ components: description: The date of publication of the last issue in this event. format: date thumbnail: + description: The representative image for this event. $ref: '#/components/schemas/Image' comics: + description: A resource list containing the comics in this event. $ref: '#/components/schemas/ComicList' stories: + description: A resource list containing the stories in this event. $ref: '#/components/schemas/StoryList' series: + description: A resource list containing the series in this event. $ref: '#/components/schemas/SeriesList' characters: + description: A resource list containing the characters which appear in this event. $ref: '#/components/schemas/CharacterList' creators: + description: A resource list containing the creators whose work appears in this event. $ref: '#/components/schemas/CreatorList' next: $ref: '#/components/schemas/EventSummary' + description: A summary representation of the event which follows this event. previous: + description: A summary representation of the event which preceded this event. $ref: '#/components/schemas/EventSummary' - ComicDataContainer: - type: object - properties: - offset: - type: integer - description: The requested offset (number of skipped results) of the call. - format: int32 - limit: - type: integer - description: The requested result limit. - format: int32 - total: - type: integer - description: The total number of resources available given the current filter - set. - format: int32 - count: - type: integer - description: The total number of results returned by this call. - format: int32 - results: - type: array - description: The list of comics returned by the call - items: - $ref: '#/components/schemas/Comic' - TextObject: - type: object - properties: - type: - type: string - description: "The canonical type of the text object (e.g. solicit text,\ - \ preview text, etc.)." - language: - type: string - description: The IETF language tag denoting the language the text object - is written in. - text: - type: string - description: The text. - CreatorDataWrapper: - type: object - properties: - code: - type: integer - description: The HTTP status code of the returned result. - format: int32 - status: - type: string - description: A string description of the call status. - copyright: - type: string - description: The copyright notice for the returned result. - attributionText: - type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: - type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/CreatorDataContainer' - etag: - type: string - description: A digest value of the content returned by the call. - StoryDataWrapper: - type: object - properties: - code: - type: integer - description: The HTTP status code of the returned result. - format: int32 - status: - type: string - description: A string description of the call status. - copyright: - type: string - description: The copyright notice for the returned result. - attributionText: - type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: - type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/StoryDataContainer' - etag: - type: string - description: A digest value of the content returned by the call. - Character: - type: object - properties: - id: - type: integer - description: The unique ID of the character resource. - format: int32 - name: - type: string - description: The name of the character. - description: - type: string - description: A short bio or description of the character. - modified: - type: string - description: The date the resource was most recently modified. - format: date - resourceURI: - type: string - description: The canonical URL identifier for this resource. - urls: - type: array - description: A set of public web site URLs for the resource. - items: - $ref: '#/components/schemas/Url' - thumbnail: - $ref: '#/components/schemas/Image' - comics: - $ref: '#/components/schemas/ComicList' - stories: - $ref: '#/components/schemas/StoryList' - events: - $ref: '#/components/schemas/EventList' - series: - $ref: '#/components/schemas/SeriesList' - CharacterDataWrapper: - type: object - properties: - code: - type: integer - description: The HTTP status code of the returned result. - format: int32 - status: - type: string - description: A string description of the call status. - copyright: - type: string - description: The copyright notice for the returned result. - attributionText: - type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: - type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/CharacterDataContainer' - etag: - type: string - description: A digest value of the content returned by the call. - ComicDataWrapper: - type: object - properties: - code: - type: integer - description: The HTTP status code of the returned result. - format: int32 - status: - type: string - description: A string description of the call status. - copyright: - type: string - description: The copyright notice for the returned result. - attributionText: - type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: - type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/ComicDataContainer' - etag: - type: string - description: A digest value of the content returned by the call. + required: + - id + - title + - description + - resourceURI + - urls + - modified + - start + - end + - thumbnail + - comics + - stories + - series + - characters + - creators + - next + - previous Series: type: object + description: A series resource type that represents (usually) sequentially number list of comics with the same title and volume (e.g. Uncanny X-Men). Marvel uses the year of original publication for a series as the volume number. properties: id: type: integer @@ -5481,8 +5244,7 @@ components: format: int32 endYear: type: integer - description: "The last year of publication for the series (conventionally,\ - \ 2099 for ongoing series) ." + description: "The last year of publication for the series (conventionally, 2099 for ongoing series)." format: int32 rating: type: string @@ -5492,51 +5254,482 @@ components: description: The date the resource was most recently modified. format: date thumbnail: + description: The representative image for this series. $ref: '#/components/schemas/Image' comics: + description: A resource list containing comics in this series. $ref: '#/components/schemas/ComicList' stories: + description: A resource list containing stories which occur in comics in this series. $ref: '#/components/schemas/StoryList' events: + description: A resource list containing events which take place in comics in this series. $ref: '#/components/schemas/EventList' characters: + description: A resource list containing characters which appear in comics in this series. $ref: '#/components/schemas/CharacterList' creators: + description: A resource list containing creators whose work appears in comics in this series. $ref: '#/components/schemas/CreatorList' next: + description: A summary representation of the series which follows this series. $ref: '#/components/schemas/SeriesSummary' previous: + description: A summary representation of the series which preceded this series. $ref: '#/components/schemas/SeriesSummary' - SeriesDataWrapper: + required: + - id + - title + - description + - resourceURI + - urls + - startYear + - endYear + - rating + - modified + - thumbnail + - comics + - stories + - events + - characters + - creators + - next + - previous + Story: type: object + description: A story resource type that represents an indivisible, reusable components of comics. Most comics have two stories - a cover and an interior story (e. g. the cover from Amazing Fantasy \#15 and the origin of Spider-Man story from that comic) - but many, such as anthology comics and collections, will have more. Stories may be re-published in several comics, but the comic in which they originally appeared will always be present as a data point. properties: - code: + id: type: integer - description: The HTTP status code of the returned result. + description: The unique ID of the story resource. format: int32 - status: + title: type: string - description: A string description of the call status. - copyright: + description: The story title. + description: type: string - description: The copyright notice for the returned result. - attributionText: + description: A short description of the story. + resourceURI: type: string - description: The attribution notice for this result. Please display either - this notice or the contents of the attributionHTML field on all screens - which contain data from the Marvel Comics API. - attributionHTML: + description: The canonical URL identifier for this resource. + type: type: string - description: An HTML representation of the attribution notice for this result. Please - display either this notice or the contents of the attributionText field - on all screens which contain data from the Marvel Comics API. - data: - $ref: '#/components/schemas/SeriesDataContainer' - etag: + description: The story type (e.g. interior story, cover, text story). + modified: type: string - description: A digest value of the content returned by the call. + description: The date the resource was most recently modified. + format: date + thumbnail: + description: The representative image for this story. + $ref: '#/components/schemas/Image' + comics: + description: A resource list containing comics in which this story takes place. + $ref: '#/components/schemas/ComicList' + series: + description: A resource list containing series in which this story appears. + $ref: '#/components/schemas/SeriesList' + events: + description: A resource list containing events in which this story appears. + $ref: '#/components/schemas/EventList' + characters: + description: A resource list containing characters which appear in this story. + $ref: '#/components/schemas/CharacterList' + creators: + description: A resource list containing creators worked on this story. + $ref: '#/components/schemas/CreatorList' + originalissue: + description: A summary representation of the issue in which this story was originally published. + $ref: '#/components/schemas/ComicSummary' + required: + - id + - title + - description + - resourceURI + - type + - modified + - thumbnail + - comics + - series + - events + - characters + - creators + - originalissue + +# Core Entity Summary Representations + CharacterSummary: + type: object + description: A type that represents a summary of a character resource. + properties: + resourceURI: + type: string + description: The path to the individual character resource. + name: + type: string + description: The full name of the character. + role: + type: string + description: The role of the creator in the parent entity. + required: + - resourceURI + - name + - role + ComicSummary: + type: object + description: A type that represents a summary of a comic resource. + properties: + resourceURI: + type: string + description: The path to the individual comic resource. + name: + type: string + description: The canonical name of the comic. + required: + - resourceURI + - name + CreatorSummary: + type: object + description: A type that represents a summary of a creator resource. + properties: + resourceURI: + type: string + description: The path to the individual creator resource. + name: + type: string + description: The full name of the creator. + role: + type: string + description: The role of the creator in the parent entity. + required: + - resourceURI + - name + - role + EventSummary: + type: object + description: A type that represents a summary of an event resource. + properties: + resourceURI: + type: string + description: The path to the individual event resource. + name: + type: string + description: The name of the event. + required: + - resourceURI + - name + SeriesSummary: + type: object + description: A type that represents a summary of a series resource. + properties: + resourceURI: + type: string + description: The path to the individual series resource. + name: + type: string + description: The canonical name of the series. + required: + - resourceURI + - name + StorySummary: + type: object + description: A type that represents a summary of a story resource. + properties: + resourceURI: + type: string + description: The path to the individual story resource. + name: + type: string + description: The canonical name of the story. + type: + type: string + description: The type of the story (interior or cover). + required: + - resourceURI + - name + - type + +# Core Entity List Representations + CharacterList: + type: object + description: A resource list containing characters which appear in this story. + properties: + available: + type: integer + description: The number of total available characters in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of characters returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of characters in this collection. + items: + type: array + description: The list of returned characters in this collection. + items: + $ref: '#/components/schemas/CharacterSummary' + required: + - available + - returned + - collectionURI + - items + ComicList: + type: object + description: A resource list containing comics which feature this story. + properties: + available: + type: integer + description: The number of total available issues in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of issues returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of issues in this collection. + items: + type: array + description: The list of returned issues in this collection. + items: + $ref: '#/components/schemas/ComicSummary' + required: + - available + - returned + - collectionURI + - items + CreatorList: + type: object + description: A resource list containing creators whose work appears in this story. + properties: + available: + type: integer + description: The number of total available creators in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of creators returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of creators in this collection. + items: + type: array + description: The list of returned creators in this collection. + items: + $ref: '#/components/schemas/CreatorSummary' + required: + - available + - returned + - collectionURI + - items + EventList: + type: object + description: A resource list containing events which feature this story. + properties: + available: + type: integer + description: The number of total available events in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of events returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of events in this collection. + items: + type: array + description: The list of returned events in this collection. + items: + $ref: '#/components/schemas/EventSummary' + required: + - available + - returned + - collectionURI + - items + SeriesList: + type: object + description: A resource list containing series in which this story appears. + properties: + available: + type: integer + description: The number of total available series in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of series returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of series in this collection. + items: + type: array + description: The list of returned series in this collection. + items: + $ref: '#/components/schemas/SeriesSummary' + required: + - available + - returned + - collectionURI + - items + StoryList: + type: object + description: A resource list containing stories which are related to this story. + properties: + available: + type: integer + description: The number of total available stories in this list. Will always be greater than or equal to the "returned" value. + format: int32 + returned: + type: integer + description: The number of stories returned in this collection (up to 20). + format: int32 + collectionURI: + type: string + description: The path to the full list of stories in this collection. + items: + type: array + description: The list of returned stories in this collection. + items: + $ref: '#/components/schemas/StorySummary' + required: + - available + - returned + - collectionURI + - items + +# Core Entity Container Representations + CharacterDataContainer: + type: object + description: The container for the character data. + properties: + offset: + type: integer + description: The requested offset (number of skipped results) of the call. + format: int32 + limit: + type: integer + description: The requested result limit. + format: int32 + total: + type: integer + description: The total number of resources available given the current filter + set. + format: int32 + count: + type: integer + description: The total number of results returned by this call. + format: int32 + results: + type: array + description: The list of characters returned by the call. + items: + $ref: '#/components/schemas/Character' + required: + - offset + - limit + - total + - count + - results + ComicDataContainer: + type: object + description: The container for the comic data. + properties: + offset: + type: integer + description: The requested offset (number of skipped results) of the call. + format: int32 + limit: + type: integer + description: The requested result limit. + format: int32 + total: + type: integer + description: The total number of resources available given the current filter + set. + format: int32 + count: + type: integer + description: The total number of results returned by this call. + format: int32 + results: + type: array + description: The list of comics returned by the call + items: + $ref: '#/components/schemas/Comic' + required: + - offset + - limit + - total + - count + - results + CreatorDataContainer: + type: object + description: A container type for lists of creators. + properties: + offset: + type: integer + description: The requested offset (number of skipped results) of the call. + format: int32 + limit: + type: integer + description: The requested result limit. + format: int32 + total: + type: integer + description: The total number of resources available given the current filter set. + format: int32 + count: + type: integer + description: The total number of results returned by this call. + format: int32 + results: + type: array + description: The list of creators returned by the call. + items: + $ref: '#/components/schemas/Creator' + required: + - offset + - limit + - total + - count + - results + EventDataContainer: + type: object + description: The container for the event data. + properties: + offset: + type: integer + description: The requested offset (number of skipped results) of the call. + format: int32 + limit: + type: integer + description: The requested result limit. + format: int32 + total: + type: integer + description: The total number of resources available given the current filter + set. + format: int32 + count: + type: integer + description: The total number of results returned by this call. + format: int32 + results: + type: array + description: The list of events returned by the call + items: + $ref: '#/components/schemas/Event' + required: + - offset + - limit + - total + - count + - results SeriesDataContainer: type: object + description: The container for the series data. properties: offset: type: integer @@ -5560,8 +5753,15 @@ components: description: The list of series returned by the call items: $ref: '#/components/schemas/Series' + required: + - offset + - limit + - total + - count + - results StoryDataContainer: type: object + description: The container for the story data. properties: offset: type: integer @@ -5585,188 +5785,294 @@ components: description: The list of stories returned by the call items: $ref: '#/components/schemas/Story' - Comic: + required: + - offset + - limit + - total + - count + - results + +# Core Entity Wrapper Representations + CharacterDataWrapper: type: object + description: The wrapper for the character data. properties: - id: + code: type: integer - description: The unique ID of the comic resource. + description: The HTTP status code of the returned result. format: int32 - digitalId: - type: integer - description: The ID of the digital comic representation of this comic. Will - be 0 if the comic is not available digitally. - format: int32 - title: + status: type: string - description: The canonical title of the comic. - issueNumber: - type: number - description: The number of the issue in the series (will generally be 0 - for collection formats). - format: double - variantDescription: + description: A string description of the call status. + copyright: type: string - description: "If the issue is a variant (e.g. an alternate cover, second\ - \ printing, or director’s cut), a text description of the variant." - description: + description: The copyright notice for the returned result. + attributionText: type: string - description: The preferred description of the comic. - modified: + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: type: string - description: The date the resource was most recently modified. - format: date - isbn: + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/CharacterDataContainer' + etag: type: string - description: The ISBN for the comic (generally only populated for collection - formats). - upc: - type: string - description: The UPC barcode number for the comic (generally only populated - for periodical formats). - diamondCode: - type: string - description: The Diamond code for the comic. - ean: - type: string - description: The EAN barcode for the comic. - issn: - type: string - description: The ISSN barcode for the comic. - format: - type: string - description: "The publication format of the comic e.g. comic, hardcover,\ - \ trade paperback." - pageCount: - type: integer - description: The number of story pages in the comic. - format: int32 - textObjects: - type: array - description: A set of descriptive text blurbs for the comic. - items: - $ref: '#/components/schemas/TextObject' - resourceURI: - type: string - description: The canonical URL identifier for this resource. - urls: - type: array - description: A set of public web site URLs for the resource. - items: - $ref: '#/components/schemas/Url' - series: - $ref: '#/components/schemas/SeriesSummary' - variants: - type: array - description: A list of variant issues for this comic (includes the "original" - issue if the current issue is a variant). - items: - $ref: '#/components/schemas/ComicSummary' - collections: - type: array - description: A list of collections which include this comic (will generally - be empty if the comic's format is a collection). - items: - $ref: '#/components/schemas/ComicSummary' - collectedIssues: - type: array - description: A list of issues collected in this comic (will generally be - empty for periodical formats such as "comic" or "magazine"). - items: - $ref: '#/components/schemas/ComicSummary' - dates: - type: array - description: A list of key dates for this comic. - items: - $ref: '#/components/schemas/ComicDate' - prices: - type: array - description: A list of prices for this comic. - items: - $ref: '#/components/schemas/ComicPrice' - thumbnail: - $ref: '#/components/schemas/Image' - images: - type: array - description: A list of promotional images associated with this comic. - items: - $ref: '#/components/schemas/Image' - creators: - $ref: '#/components/schemas/CreatorList' - characters: - $ref: '#/components/schemas/CharacterList' - stories: - $ref: '#/components/schemas/StoryList' - events: - $ref: '#/components/schemas/EventList' - CreatorDataContainer: + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + ComicDataWrapper: type: object + description: The wrapper for the comic data. properties: - offset: + code: type: integer - description: The requested offset (number of skipped results) of the call. + description: The HTTP status code of the returned result. format: int32 - limit: - type: integer - description: The requested result limit. - format: int32 - total: - type: integer - description: The total number of resources available given the current filter - set. - format: int32 - count: - type: integer - description: The total number of results returned by this call. - format: int32 - results: - type: array - description: The list of creators returned by the call. - items: - $ref: '#/components/schemas/Creator' - Story: + status: + type: string + description: A string description of the call status. + copyright: + type: string + description: The copyright notice for the returned result. + attributionText: + type: string + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: + type: string + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/ComicDataContainer' + etag: + type: string + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + CreatorDataWrapper: type: object + description: The wrapper for the creator data. properties: - id: + code: type: integer - description: The unique ID of the story resource. + description: The HTTP status code of the returned result. format: int32 - title: + status: type: string - description: The story title. - description: + description: A string description of the call status. + copyright: type: string - description: A short description of the story. - resourceURI: + description: The copyright notice for the returned result. + attributionText: type: string - description: 'The canonical URL identifier for this resource. ' + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: + type: string + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/CreatorDataContainer' + etag: + type: string + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + EventDataWrapper: + type: object + description: The wrapper for the event data. + properties: + code: + type: integer + description: The HTTP status code of the returned result. + format: int32 + status: + type: string + description: A string description of the call status. + copyright: + type: string + description: The copyright notice for the returned result. + attributionText: + type: string + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: + type: string + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/EventDataContainer' + etag: + type: string + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + SeriesDataWrapper: + type: object + description: The wrapper for the series data. + properties: + code: + type: integer + description: The HTTP status code of the returned result. + format: int32 + status: + type: string + description: A string description of the call status. + copyright: + type: string + description: The copyright notice for the returned result. + attributionText: + type: string + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: + type: string + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/SeriesDataContainer' + etag: + type: string + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + StoryDataWrapper: + type: object + description: The wrapper for the story data. + properties: + code: + type: integer + description: The HTTP status code of the returned result. + format: int32 + status: + type: string + description: A string description of the call status. + copyright: + type: string + description: The copyright notice for the returned result. + attributionText: + type: string + description: The attribution notice for this result. Please display either this notice or the contents of the attributionHTML field on all screens which contain data from the Marvel Comics API. + attributionHTML: + type: string + description: An HTML representation of the attribution notice for this result. Please display either this notice or the contents of the attributionText field on all screens which contain data from the Marvel Comics API. + data: + $ref: '#/components/schemas/StoryDataContainer' + etag: + type: string + description: A digest value of the content returned by the call. + required: + - code + - status + - copyright + - attributionText + - attributionHTML + - data + - etag + +# Common Structures + ComicDate: + type: object + description: A type that represents a date and time for which the comic was released. + properties: type: type: string - description: "The story type e.g. interior story, cover, text story." - modified: + description: "A description of the date (e.g. onsale date, FOC date)." + date: type: string - description: The date the resource was most recently modified. + description: The date. format: date - thumbnail: - $ref: '#/components/schemas/Image' - comics: - $ref: '#/components/schemas/ComicList' - series: - $ref: '#/components/schemas/SeriesList' - events: - $ref: '#/components/schemas/EventList' - characters: - $ref: '#/components/schemas/CharacterList' - creators: - $ref: '#/components/schemas/CreatorList' - originalissue: - $ref: '#/components/schemas/ComicSummary' - ErrorResponse: + required: + - type + - date + ComicPrice: type: object - description: This is the standard error response type. + description: A type that represents a price (e.g. print price, digital price) for the comic. + properties: + type: + type: string + description: "A description of the price (e.g. print price, digital price)." + price: + type: number + description: The price (all prices in USD). + format: float + required: + - type + - price + Image: + type: object + description: A type that represents an image for a resource. + properties: + path: + type: string + description: The directory path of to the image. + extension: + type: string + description: The file extension for the image. + required: + - path + - extension + TextObject: + type: object + description: A type that represents bits of descriptive text which are attached to an entity. + properties: + type: + type: string + description: "The canonical type of the text object (e.g. solicit text, preview text, etc.)." + language: + type: string + description: The IETF language tag (or language code) denoting which language the text object is written in. + text: + type: string + description: The text of the text object. + required: + - type + - language + - text + Url: + type: object + description: A type that represents a reference to web pages or deep links into applications. When present in a resultset, it is preferred that you use these to link back to Marvel. Many resources will have more than one representation on the web so URLs are generally presented as an array of URL resources. + properties: + type: + type: string + description: A text identifier for the URL. + url: + type: string + description: "A full URL (including scheme, domain, and path)." + required: + - type + - url + +# Errors + StandardError: + type: object + description: A standard error type. properties: code: type: string description: The HTTP status code of the returned result. required: - - code \ No newline at end of file + - code + \ No newline at end of file