{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DuplicateRecordFields #-}
{-# LANGUAGE NamedFieldPuns #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE RecordWildCards #-}
{-# LANGUAGE StrictData #-}
{-# LANGUAGE NoImplicitPrelude #-}
{-# OPTIONS_GHC -fno-warn-unused-imports #-}
{-# OPTIONS_GHC -fno-warn-unused-matches #-}

-- Derived from AWS service descriptions, licensed under Apache 2.0.

-- |
-- Module      : Amazonka.APIGateway.Types.DocumentationPart
-- Copyright   : (c) 2013-2021 Brendan Hay
-- License     : Mozilla Public License, v. 2.0.
-- Maintainer  : Brendan Hay <brendan.g.hay+amazonka@gmail.com>
-- Stability   : auto-generated
-- Portability : non-portable (GHC extensions)
module Amazonka.APIGateway.Types.DocumentationPart where

import Amazonka.APIGateway.Types.DocumentationPartLocation
import qualified Amazonka.Core as Core
import qualified Amazonka.Lens as Lens
import qualified Amazonka.Prelude as Prelude

-- | A documentation part for a targeted API entity.
--
-- A documentation part consists of a content map (@properties@) and a
-- target (@location@). The target specifies an API entity to which the
-- documentation content applies. The supported API entity types are @API@,
-- @AUTHORIZER@, @MODEL@, @RESOURCE@, @METHOD@, @PATH_PARAMETER@,
-- @QUERY_PARAMETER@, @REQUEST_HEADER@, @REQUEST_BODY@, @RESPONSE@,
-- @RESPONSE_HEADER@, and @RESPONSE_BODY@. Valid @location@ fields depend
-- on the API entity type. All valid fields are not required.
--
-- The content map is a JSON string of API-specific key-value pairs.
-- Although an API can use any shape for the content map, only the
-- OpenAPI-compliant documentation fields will be injected into the
-- associated API entity definition in the exported OpenAPI definition
-- file.
--
-- <https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-documenting-api.html Documenting an API>,
-- DocumentationParts
--
-- /See:/ 'newDocumentationPart' smart constructor.
data DocumentationPart = DocumentationPart'
  { -- | The location of the API entity to which the documentation applies. Valid
    -- fields depend on the targeted API entity type. All the valid location
    -- fields are not required. If not explicitly specified, a valid location
    -- field is treated as a wildcard and associated documentation content may
    -- be inherited by matching entities, unless overridden.
    DocumentationPart -> Maybe DocumentationPartLocation
location :: Prelude.Maybe DocumentationPartLocation,
    -- | The DocumentationPart identifier, generated by API Gateway when the
    -- @DocumentationPart@ is created.
    DocumentationPart -> Maybe Text
id :: Prelude.Maybe Prelude.Text,
    -- | A content map of API-specific key-value pairs describing the targeted
    -- API entity. The map must be encoded as a JSON string, e.g.,
    -- @\"{ \\\"description\\\": \\\"The API does ...\\\" }\"@. Only
    -- OpenAPI-compliant documentation-related fields from the properties map
    -- are exported and, hence, published as part of the API entity
    -- definitions, while the original documentation parts are exported in a
    -- OpenAPI extension of @x-amazon-apigateway-documentation@.
    DocumentationPart -> Maybe Text
properties :: Prelude.Maybe Prelude.Text
  }
  deriving (DocumentationPart -> DocumentationPart -> Bool
(DocumentationPart -> DocumentationPart -> Bool)
-> (DocumentationPart -> DocumentationPart -> Bool)
-> Eq DocumentationPart
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: DocumentationPart -> DocumentationPart -> Bool
$c/= :: DocumentationPart -> DocumentationPart -> Bool
== :: DocumentationPart -> DocumentationPart -> Bool
$c== :: DocumentationPart -> DocumentationPart -> Bool
Prelude.Eq, ReadPrec [DocumentationPart]
ReadPrec DocumentationPart
Int -> ReadS DocumentationPart
ReadS [DocumentationPart]
(Int -> ReadS DocumentationPart)
-> ReadS [DocumentationPart]
-> ReadPrec DocumentationPart
-> ReadPrec [DocumentationPart]
-> Read DocumentationPart
forall a.
(Int -> ReadS a)
-> ReadS [a] -> ReadPrec a -> ReadPrec [a] -> Read a
readListPrec :: ReadPrec [DocumentationPart]
$creadListPrec :: ReadPrec [DocumentationPart]
readPrec :: ReadPrec DocumentationPart
$creadPrec :: ReadPrec DocumentationPart
readList :: ReadS [DocumentationPart]
$creadList :: ReadS [DocumentationPart]
readsPrec :: Int -> ReadS DocumentationPart
$creadsPrec :: Int -> ReadS DocumentationPart
Prelude.Read, Int -> DocumentationPart -> ShowS
[DocumentationPart] -> ShowS
DocumentationPart -> String
(Int -> DocumentationPart -> ShowS)
-> (DocumentationPart -> String)
-> ([DocumentationPart] -> ShowS)
-> Show DocumentationPart
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
showList :: [DocumentationPart] -> ShowS
$cshowList :: [DocumentationPart] -> ShowS
show :: DocumentationPart -> String
$cshow :: DocumentationPart -> String
showsPrec :: Int -> DocumentationPart -> ShowS
$cshowsPrec :: Int -> DocumentationPart -> ShowS
Prelude.Show, (forall x. DocumentationPart -> Rep DocumentationPart x)
-> (forall x. Rep DocumentationPart x -> DocumentationPart)
-> Generic DocumentationPart
forall x. Rep DocumentationPart x -> DocumentationPart
forall x. DocumentationPart -> Rep DocumentationPart x
forall a.
(forall x. a -> Rep a x) -> (forall x. Rep a x -> a) -> Generic a
$cto :: forall x. Rep DocumentationPart x -> DocumentationPart
$cfrom :: forall x. DocumentationPart -> Rep DocumentationPart x
Prelude.Generic)

-- |
-- Create a value of 'DocumentationPart' with all optional fields omitted.
--
-- Use <https://hackage.haskell.org/package/generic-lens generic-lens> or <https://hackage.haskell.org/package/optics optics> to modify other optional fields.
--
-- The following record fields are available, with the corresponding lenses provided
-- for backwards compatibility:
--
-- 'location', 'documentationPart_location' - The location of the API entity to which the documentation applies. Valid
-- fields depend on the targeted API entity type. All the valid location
-- fields are not required. If not explicitly specified, a valid location
-- field is treated as a wildcard and associated documentation content may
-- be inherited by matching entities, unless overridden.
--
-- 'id', 'documentationPart_id' - The DocumentationPart identifier, generated by API Gateway when the
-- @DocumentationPart@ is created.
--
-- 'properties', 'documentationPart_properties' - A content map of API-specific key-value pairs describing the targeted
-- API entity. The map must be encoded as a JSON string, e.g.,
-- @\"{ \\\"description\\\": \\\"The API does ...\\\" }\"@. Only
-- OpenAPI-compliant documentation-related fields from the properties map
-- are exported and, hence, published as part of the API entity
-- definitions, while the original documentation parts are exported in a
-- OpenAPI extension of @x-amazon-apigateway-documentation@.
newDocumentationPart ::
  DocumentationPart
newDocumentationPart :: DocumentationPart
newDocumentationPart =
  DocumentationPart' :: Maybe DocumentationPartLocation
-> Maybe Text -> Maybe Text -> DocumentationPart
DocumentationPart'
    { $sel:location:DocumentationPart' :: Maybe DocumentationPartLocation
location = Maybe DocumentationPartLocation
forall a. Maybe a
Prelude.Nothing,
      $sel:id:DocumentationPart' :: Maybe Text
id = Maybe Text
forall a. Maybe a
Prelude.Nothing,
      $sel:properties:DocumentationPart' :: Maybe Text
properties = Maybe Text
forall a. Maybe a
Prelude.Nothing
    }

-- | The location of the API entity to which the documentation applies. Valid
-- fields depend on the targeted API entity type. All the valid location
-- fields are not required. If not explicitly specified, a valid location
-- field is treated as a wildcard and associated documentation content may
-- be inherited by matching entities, unless overridden.
documentationPart_location :: Lens.Lens' DocumentationPart (Prelude.Maybe DocumentationPartLocation)
documentationPart_location :: (Maybe DocumentationPartLocation
 -> f (Maybe DocumentationPartLocation))
-> DocumentationPart -> f DocumentationPart
documentationPart_location = (DocumentationPart -> Maybe DocumentationPartLocation)
-> (DocumentationPart
    -> Maybe DocumentationPartLocation -> DocumentationPart)
-> Lens
     DocumentationPart
     DocumentationPart
     (Maybe DocumentationPartLocation)
     (Maybe DocumentationPartLocation)
forall s a b t. (s -> a) -> (s -> b -> t) -> Lens s t a b
Lens.lens (\DocumentationPart' {Maybe DocumentationPartLocation
location :: Maybe DocumentationPartLocation
$sel:location:DocumentationPart' :: DocumentationPart -> Maybe DocumentationPartLocation
location} -> Maybe DocumentationPartLocation
location) (\s :: DocumentationPart
s@DocumentationPart' {} Maybe DocumentationPartLocation
a -> DocumentationPart
s {$sel:location:DocumentationPart' :: Maybe DocumentationPartLocation
location = Maybe DocumentationPartLocation
a} :: DocumentationPart)

-- | The DocumentationPart identifier, generated by API Gateway when the
-- @DocumentationPart@ is created.
documentationPart_id :: Lens.Lens' DocumentationPart (Prelude.Maybe Prelude.Text)
documentationPart_id :: (Maybe Text -> f (Maybe Text))
-> DocumentationPart -> f DocumentationPart
documentationPart_id = (DocumentationPart -> Maybe Text)
-> (DocumentationPart -> Maybe Text -> DocumentationPart)
-> Lens
     DocumentationPart DocumentationPart (Maybe Text) (Maybe Text)
forall s a b t. (s -> a) -> (s -> b -> t) -> Lens s t a b
Lens.lens (\DocumentationPart' {Maybe Text
id :: Maybe Text
$sel:id:DocumentationPart' :: DocumentationPart -> Maybe Text
id} -> Maybe Text
id) (\s :: DocumentationPart
s@DocumentationPart' {} Maybe Text
a -> DocumentationPart
s {$sel:id:DocumentationPart' :: Maybe Text
id = Maybe Text
a} :: DocumentationPart)

-- | A content map of API-specific key-value pairs describing the targeted
-- API entity. The map must be encoded as a JSON string, e.g.,
-- @\"{ \\\"description\\\": \\\"The API does ...\\\" }\"@. Only
-- OpenAPI-compliant documentation-related fields from the properties map
-- are exported and, hence, published as part of the API entity
-- definitions, while the original documentation parts are exported in a
-- OpenAPI extension of @x-amazon-apigateway-documentation@.
documentationPart_properties :: Lens.Lens' DocumentationPart (Prelude.Maybe Prelude.Text)
documentationPart_properties :: (Maybe Text -> f (Maybe Text))
-> DocumentationPart -> f DocumentationPart
documentationPart_properties = (DocumentationPart -> Maybe Text)
-> (DocumentationPart -> Maybe Text -> DocumentationPart)
-> Lens
     DocumentationPart DocumentationPart (Maybe Text) (Maybe Text)
forall s a b t. (s -> a) -> (s -> b -> t) -> Lens s t a b
Lens.lens (\DocumentationPart' {Maybe Text
properties :: Maybe Text
$sel:properties:DocumentationPart' :: DocumentationPart -> Maybe Text
properties} -> Maybe Text
properties) (\s :: DocumentationPart
s@DocumentationPart' {} Maybe Text
a -> DocumentationPart
s {$sel:properties:DocumentationPart' :: Maybe Text
properties = Maybe Text
a} :: DocumentationPart)

instance Core.FromJSON DocumentationPart where
  parseJSON :: Value -> Parser DocumentationPart
parseJSON =
    String
-> (Object -> Parser DocumentationPart)
-> Value
-> Parser DocumentationPart
forall a. String -> (Object -> Parser a) -> Value -> Parser a
Core.withObject
      String
"DocumentationPart"
      ( \Object
x ->
          Maybe DocumentationPartLocation
-> Maybe Text -> Maybe Text -> DocumentationPart
DocumentationPart'
            (Maybe DocumentationPartLocation
 -> Maybe Text -> Maybe Text -> DocumentationPart)
-> Parser (Maybe DocumentationPartLocation)
-> Parser (Maybe Text -> Maybe Text -> DocumentationPart)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
Prelude.<$> (Object
x Object -> Text -> Parser (Maybe DocumentationPartLocation)
forall a. FromJSON a => Object -> Text -> Parser (Maybe a)
Core..:? Text
"location")
            Parser (Maybe Text -> Maybe Text -> DocumentationPart)
-> Parser (Maybe Text) -> Parser (Maybe Text -> DocumentationPart)
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
Prelude.<*> (Object
x Object -> Text -> Parser (Maybe Text)
forall a. FromJSON a => Object -> Text -> Parser (Maybe a)
Core..:? Text
"id")
            Parser (Maybe Text -> DocumentationPart)
-> Parser (Maybe Text) -> Parser DocumentationPart
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
Prelude.<*> (Object
x Object -> Text -> Parser (Maybe Text)
forall a. FromJSON a => Object -> Text -> Parser (Maybe a)
Core..:? Text
"properties")
      )

instance Prelude.Hashable DocumentationPart

instance Prelude.NFData DocumentationPart