First version of the library documentation (#7)

This PR contains the work done to write the main article of the `DocC` documentation for the library, which introduces the library as well as explains how to install it and use it.

Reviewed-on: #7
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

README.md

@@ -1 +1,37 @@
+[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Frock-n-code%2Fmarvel-service%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/rock-n-code/marvel-service)
+[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Frock-n-code%2Fmarvel-service%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/rock-n-code/marvel-service)
+
 # Marvel Service
+
+A library written entirely with [Swift](https://www.swift.org) that allow the developer to interacts with the [Marvel API](https://developer.marvel.com) backend service.
+
+## Installation
+
+To use this library with your package, then add it as a dependency in the `Package.swift` file:
+
+```swift
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        .package(url: "https://github.com/rock-n-code/marvel-service", from: "1.0.0"),
+        // other dependencies
+    ],
+    targets: [
+        .target(
+            name: "SomeTarget", 
+            dependencies: [
+                .product(name: "MarvelService", package: "marvel-service"),
+            ]
+        )
+        // other targets
+    ]
+)
+```
+
+It is also possible to use this library with your app in Xcode, then add it as a dependency in your Xcode project.
+
+> important: Swift 5.10 or higher is required in order to compile this library.
+
+## Documentation
+
+Please refer to the [online documentation](https://rock-n-code.github.io/marvel-service/documentation/marvelservice/) for further informations about this library.

Sources/MarvelService/Catalogs/MarvelService.docc/Library.md

@@ -1,13 +1,191 @@
 # ``MarvelService``
 
-<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
+A library that allows the developer to interact with the **Marvel Comics API** backend service.
 
 ## Overview
 
-<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+The **MarvelService** library is a package that allows the developer to interact with all the available endpoints of the [Marvel Comics online service](https://developer.marvel.com).
+
+## Installation
+
+This library can be integrated into your library, tool, and/or app as an added dependency into any `Package.swift` file or Xcode project with the [Swift Package Manager](https://developer.apple.com/documentation/xcode/swift-packages).
+
+Here's an example of how to add this library as a dependency into a `Package.swift` file:
+
+```swift
+let package = Package(
+    // name, platforms, products, etc.
+    dependencies: [
+        .package(url: "https://github.com/rock-n-code/marvel-service", from: "1.0.0"),
+        // other dependencies
+    ],
+    targets: [
+        .target(
+            name: "SomeTarget", 
+            dependencies: [
+                .product(name: "MarvelService", package: "marvel-service"),
+            ]
+        )
+        // other targets
+    ]
+)
+```
+
+In [Xcode](https://developer.apple.com/xcode/), on the other hand, it is required to use the Xcode inerface to add dependencies into a project or workspace.
+
+> important: Swift 5.10 or higher is required in order to build this library.
+
+## Usage
+
+After adding the `MarvelService` library as a dependency in the library, tool, and/or application, as explained in the previous sec tion, then it is required to import the library.
+
+```swift
+import MarvelService
+```
+
+Then a ``Client`` must to be initialized. Although this type is highly configurable, and browsing through its documentation is highly recomendable; it requires three parameters to set the client correctly:
+
+1. *a host URL to which the client connects to*;
+2. *a transport in charge of performing the HTTP operations*;
+3. *an authorization middleware configured with either an `api key` or a `private+public` keys*. 
+
+```swift
+let marvelClient = Client(
+    serverURL: try Servers.Server1.url(),
+    transport: URLSessionTransport(),
+    middlewares: [
+        AuthMiddleware(
+            privateKey: "SomePrivateKey",
+            publicKey: "SomePublicKey"
+        )
+    ]
+)
+```
+
+> Important: It is mandatory to signup to the [Developer portal of Marvel Comics](https://developer.marvel.com/account) in order to obtain an *API Key* to use this library, as every request to this service [requires to be signed](https://developer.marvel.com/documentation/authorization).
+
+Finally a client is ready to use! This client is now able to request any information regarding to any published Marvel *characters, comics, creators, events, series and stories* to the **Marvel Comics API** service, and handle its responses as follows:
+
+```swift
+do {
+    let response = try await marvelClient.getCharacters(
+        query: .init(name: "wolverine"),
+    )
+
+    switch response {
+    case let .ok(ok):
+        switch ok.body {
+        case let .json(charactersContainer):
+            // Do something with the `charactersContainer` object.
+        }
+    case let .unauthorized(standardError):
+        // Do something with the `standardError` object.
+    case .forbidden(_):
+        // Do something here, like throwing an error.
+    case let .notFound(standardError):
+        // Do something with the `standardError` object.
+    case let .methodNotAllowed(_):
+        // Do something here, like throwing an error.
+    case let .conflict(standardError):
+        // Do something with the `standardError` object.
+    case let .tooManyRequests(_):
+        // Do something here, like throwing an error.
+    case let .undocumented(statusCode, payload):
+        // Do something with the `statusCode` and `payload` received from undeclared response, if required.
+    }
+} catch {
+    // Do something with any catched error.
+}
+```
+
+> Tip: It is highly recommended to go through the available documentation at the [Marvel Comics online service](https://developer.marvel.com)
+
+> Warning: Please do create an issue in case of encountering problems interacting with any of the endpoints.
+
+## Tasks
+
+This library offers a set of ready-to-use tasks that simplify the interaction with the library, which the developer can use from any `Terminal` application. 
+
+> Tip: To show the available list of tasks, plus display some explanations about each and every one of them; please enter the following command:
+
+```bash
+$ make
+```
 
 ## Topics
 
-### <!--@START_MENU_TOKEN@-->Group<!--@END_MENU_TOKEN@-->
+### Client
 
-- <!--@START_MENU_TOKEN@-->``Symbol``<!--@END_MENU_TOKEN@-->
+- ``Client``
+
+### Configuration
+
+- ``Servers/Server1``
+- ``AuthMiddleware``
+
+### Core Entity Containers
+
+- ``Components/Schemas/CharacterDataContainer``
+- ``Components/Schemas/ComicDataContainer``
+- ``Components/Schemas/CreatorDataContainer``
+- ``Components/Schemas/EventDataContainer``
+- ``Components/Schemas/SeriesDataContainer``
+- ``Components/Schemas/StoryDataContainer``
+
+### Core Entity Wrappers
+
+- ``Components/Schemas/CharacterDataWrapper``
+- ``Components/Schemas/ComicDataWrapper``
+- ``Components/Schemas/CreatorDataWrapper``
+- ``Components/Schemas/EventDataWrapper``
+- ``Components/Schemas/SeriesDataWrapper``
+- ``Components/Schemas/StoryDataWrapper``
+
+### Core Entity List
+
+- ``Components/Schemas/CharacterList``
+- ``Components/Schemas/ComicList``
+- ``Components/Schemas/CreatorList``
+- ``Components/Schemas/EventList``
+- ``Components/Schemas/SeriesList``
+- ``Components/Schemas/StoryList``
+
+### Core Entity Summaries
+
+- ``Components/Schemas/CharacterSummary``
+- ``Components/Schemas/ComicSummary``
+- ``Components/Schemas/CreatorSummary``
+- ``Components/Schemas/EventSummary``
+- ``Components/Schemas/SeriesSummary``
+- ``Components/Schemas/StorySummary``
+
+### Core Entities
+
+- ``Components/Schemas/Character``
+- ``Components/Schemas/Comic``
+- ``Components/Schemas/Creator``
+- ``Components/Schemas/Event``
+- ``Components/Schemas/Series``
+- ``Components/Schemas/Story``
+
+### Common Types
+
+- ``Components/Schemas/ComicDate``
+- ``Components/Schemas/ComicPrice``
+- ``Components/Schemas/Image``
+- ``Components/Schemas/TextObject``
+- ``Components/Schemas/Url``
+
+### Error Types
+
+- ``Components/Schemas/StandardError``
+
+### Namespaces
+
+- ``Components``
+- ``Operations``
+- ``Servers``
+
+### Protocols
+
+- ``APIProtocol``

Sources/MarvelService/Catalogs/MarvelService.docc/theme-settings.json

@@ -0,0 +1,5 @@
+{
+    "meta": {
+        "title": "Marvel Service"
+    }
+}

docs/data/documentation/marvelservice/authmiddleware/clientmiddleware-implementations.json

@@ -0,0 +1 @@
+{"hierarchy":{"paths":[["doc:\/\/MarvelService\/documentation\/MarvelService","doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware"]]},"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware\/ClientMiddleware-Implementations"},"topicSections":[{"title":"Instance Methods","identifiers":["doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware\/intercept(_:body:baseURL:operationID:next:)"],"generated":true,"anchor":"Instance-Methods"}],"metadata":{"modules":[{"name":"MarvelService"}],"title":"ClientMiddleware Implementations","roleHeading":"API Collection","role":"collectionGroup"},"schemaVersion":{"minor":3,"major":0,"patch":0},"kind":"article","sections":[],"variants":[{"traits":[{"interfaceLanguage":"swift"}],"paths":["\/documentation\/marvelservice\/authmiddleware\/clientmiddleware-implementations"]}],"references":{"doc://MarvelService/documentation/MarvelService/AuthMiddleware/intercept(_:body:baseURL:operationID:next:)":{"abstract":[],"role":"symbol","identifier":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware\/intercept(_:body:baseURL:operationID:next:)","title":"intercept(_:body:baseURL:operationID:next:)","fragments":[{"text":"func","kind":"keyword"},{"text":" ","kind":"text"},{"text":"intercept","kind":"identifier"},{"text":"(","kind":"text"},{"preciseIdentifier":"s:9HTTPTypes11HTTPRequestV","text":"HTTPRequest","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"text":"body","kind":"externalParam"},{"text":": ","kind":"text"},{"preciseIdentifier":"s:14OpenAPIRuntime8HTTPBodyC","text":"HTTPBody","kind":"typeIdentifier"},{"text":"?, ","kind":"text"},{"text":"baseURL","kind":"externalParam"},{"text":": ","kind":"text"},{"preciseIdentifier":"s:10Foundation3URLV","text":"URL","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"text":"operationID","kind":"externalParam"},{"text":": ","kind":"text"},{"preciseIdentifier":"s:SS","text":"String","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"text":"next","kind":"externalParam"},{"text":": (","kind":"text"},{"preciseIdentifier":"s:9HTTPTypes11HTTPRequestV","text":"HTTPRequest","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"preciseIdentifier":"s:14OpenAPIRuntime8HTTPBodyC","text":"HTTPBody","kind":"typeIdentifier"},{"text":"?, ","kind":"text"},{"preciseIdentifier":"s:10Foundation3URLV","text":"URL","kind":"typeIdentifier"},{"text":") ","kind":"text"},{"text":"async","kind":"keyword"},{"text":" ","kind":"text"},{"text":"throws","kind":"keyword"},{"text":" -> (","kind":"text"},{"preciseIdentifier":"s:9HTTPTypes12HTTPResponseV","text":"HTTPResponse","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"preciseIdentifier":"s:14OpenAPIRuntime8HTTPBodyC","text":"HTTPBody","kind":"typeIdentifier"},{"text":"?)) ","kind":"text"},{"text":"async","kind":"keyword"},{"text":" ","kind":"text"},{"text":"throws","kind":"keyword"},{"text":" -> (","kind":"text"},{"preciseIdentifier":"s:9HTTPTypes12HTTPResponseV","text":"HTTPResponse","kind":"typeIdentifier"},{"text":", ","kind":"text"},{"preciseIdentifier":"s:14OpenAPIRuntime8HTTPBodyC","text":"HTTPBody","kind":"typeIdentifier"},{"text":"?)","kind":"text"}],"kind":"symbol","type":"topic","url":"\/documentation\/marvelservice\/authmiddleware\/intercept(_:body:baseurl:operationid:next:)"},"doc://MarvelService/documentation/MarvelService":{"identifier":"doc:\/\/MarvelService\/documentation\/MarvelService","kind":"symbol","url":"\/documentation\/marvelservice","title":"MarvelService","role":"collection","abstract":[{"text":"A library that allows the developer to interact with the ","type":"text"},{"type":"strong","inlineContent":[{"text":"Marvel Comics API","type":"text"}]},{"type":"text","text":" backend service."}],"type":"topic"},"doc://MarvelService/documentation/MarvelService/AuthMiddleware":{"abstract":[{"text":"A middleware that attaches the necessary authentication parameters to the path of the request.","type":"text"}],"role":"symbol","identifier":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware","navigatorTitle":[{"text":"AuthMiddleware","kind":"identifier"}],"title":"AuthMiddleware","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AuthMiddleware","kind":"identifier"}],"kind":"symbol","type":"topic","url":"\/documentation\/marvelservice\/authmiddleware"}}}

docs/data/documentation/marvelservice/authmiddleware/init(apikey:).json

@@ -0,0 +1 @@
+{"primaryContentSections":[{"declarations":[{"platforms":["macOS"],"tokens":[{"text":"init","kind":"keyword"},{"text":"(","kind":"text"},{"text":"apiKey","kind":"externalParam"},{"text":": ","kind":"text"},{"text":"String","kind":"typeIdentifier","preciseIdentifier":"s:SS"},{"text":")","kind":"text"}],"languages":["swift"]}],"kind":"declarations"},{"kind":"parameters","parameters":[{"content":[{"type":"paragraph","inlineContent":[{"type":"text","text":"A Marvel API key."}]}],"name":"apiKey"}]},{"kind":"content","content":[{"type":"heading","anchor":"discussion","level":2,"text":"Discussion"},{"type":"paragraph","inlineContent":[{"type":"text","text":"The middleware attaches the required "},{"code":"apikey","type":"codeVoice"},{"type":"text","text":" parameter to the URI path of the intercepted request."},{"type":"text","text":" "},{"type":"text","text":"This initializer should be used for client-side applications, as indicated in the "},{"isActive":true,"type":"reference","identifier":"https:\/\/developer.marvel.com\/documentation\/authorization"}]}]}],"schemaVersion":{"patch":0,"minor":3,"major":0},"hierarchy":{"paths":[["doc:\/\/MarvelService\/documentation\/MarvelService","doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware"]]},"abstract":[{"type":"text","text":"Initializes this middleware with an api key."}],"variants":[{"traits":[{"interfaceLanguage":"swift"}],"paths":["\/documentation\/marvelservice\/authmiddleware\/init(apikey:)"]}],"kind":"symbol","sections":[],"metadata":{"title":"init(apiKey:)","fragments":[{"kind":"identifier","text":"init"},{"kind":"text","text":"("},{"kind":"externalParam","text":"apiKey"},{"kind":"text","text":": "},{"preciseIdentifier":"s:SS","kind":"typeIdentifier","text":"String"},{"kind":"text","text":")"}],"role":"symbol","externalID":"s:13MarvelService14AuthMiddlewareV6apiKeyACSS_tcfc","roleHeading":"Initializer","symbolKind":"init","modules":[{"name":"MarvelService"}]},"identifier":{"url":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware\/init(apiKey:)","interfaceLanguage":"swift"},"references":{"doc://MarvelService/documentation/MarvelService/AuthMiddleware":{"abstract":[{"text":"A middleware that attaches the necessary authentication parameters to the path of the request.","type":"text"}],"role":"symbol","identifier":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware","navigatorTitle":[{"text":"AuthMiddleware","kind":"identifier"}],"title":"AuthMiddleware","fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"text":"AuthMiddleware","kind":"identifier"}],"kind":"symbol","type":"topic","url":"\/documentation\/marvelservice\/authmiddleware"},"doc://MarvelService/documentation/MarvelService":{"identifier":"doc:\/\/MarvelService\/documentation\/MarvelService","kind":"symbol","url":"\/documentation\/marvelservice","title":"MarvelService","role":"collection","abstract":[{"text":"A library that allows the developer to interact with the ","type":"text"},{"type":"strong","inlineContent":[{"text":"Marvel Comics API","type":"text"}]},{"type":"text","text":" backend service."}],"type":"topic"},"https://developer.marvel.com/documentation/authorization":{"type":"link","url":"https:\/\/developer.marvel.com\/documentation\/authorization","identifier":"https:\/\/developer.marvel.com\/documentation\/authorization","title":"Marvel API documentation","titleInlineContent":[{"text":"Marvel API documentation","type":"text"}]},"doc://MarvelService/documentation/MarvelService/AuthMiddleware/init(apiKey:)":{"abstract":[{"type":"text","text":"Initializes this middleware with an api key."}],"role":"symbol","identifier":"doc:\/\/MarvelService\/documentation\/MarvelService\/AuthMiddleware\/init(apiKey:)","title":"init(apiKey:)","fragments":[{"kind":"identifier","text":"init"},{"kind":"text","text":"("},{"kind":"externalParam","text":"apiKey"},{"text":": ","kind":"text"},{"preciseIdentifier":"s:SS","kind":"typeIdentifier","text":"String"},{"text":")","kind":"text"}],"kind":"symbol","url":"\/documentation\/marvelservice\/authmiddleware\/init(apikey:)","type":"topic"}}}