Allow telling whether an Operation specifies security

When an operation does not include the `security` key, it means "use the
value of the top-level `security` key." When an operation *does* specify
`security`, its value overrides the top-level `security` value. We need
to be able to tell these cases apart in order to support operations
overriding the global security setting.

Here's how the spec documents this, in its description of the `security`
field, at https://swagger.io/specification/v3/#operation-object:

> A declaration of which security mechanisms can be used for this
operation. [...] This definition overrides any declared top-level
security. To remove a top-level security declaration, an empty array can
be used.

Author: adamdicarlo0

src/OpenApi/Operation.elm

@@ -135,8 +135,12 @@ deprecated (Operation operation_) =
     operation_.deprecated
 
 
-{-| -}
-security : Operation -> List SecurityRequirement
+{-| SecurityRequirements the operation specifies (possibly an empty list), or Nothing if the operation does not specify any.
+
+If an operation specifies `security`, the given value (even if it's an empty array) overrides the schema's top-level `security`. This is documented in the OpenAPI specification here: <https://swagger.io/specification/v3/#operation-object>.
+
+-}
+security : Operation -> Maybe (List SecurityRequirement)
 security (Operation operation_) =
     operation_.security
 

src/OpenApi/Types.elm

@@ -1083,7 +1083,7 @@ type alias OperationInternal =
     , responses : Dict String (ReferenceOr Response)
     , callbacks : Dict String (ReferenceOr Callback)
     , deprecated : Bool
-    , security : List SecurityRequirement
+    , security : Maybe (List SecurityRequirement)
     , servers : List Server
     }
 
@@ -1116,7 +1116,7 @@ decodeOperation =
         |> decodeOptionalDict "responses" (decodeRefOr decodeResponse)
         |> Json.Decode.Pipeline.optional "callbacks" (Json.Decode.dict (decodeRefOr decodeCallback)) Dict.empty
         |> Json.Decode.Pipeline.optional "deprecated" Json.Decode.bool False
-        |> Json.Decode.Pipeline.optional "security" (Json.Decode.list decodeSecurityRequirement) []
+        |> optionalNothing "security" (Json.Decode.list decodeSecurityRequirement)
         |> Json.Decode.Pipeline.optional "servers" (Json.Decode.list decodeServer) []
         |> Json.Decode.andThen
             (\operation ->
@@ -1140,7 +1140,8 @@ encodeOperation (Operation operation) =
     , Just ( "responses", Json.Encode.dict identity (encodeRefOr encodeResponse) operation.responses )
     , Internal.maybeEncodeDictField ( "callbacks", identity, encodeRefOr encodeCallback ) operation.callbacks
     , Just ( "deprecated", Json.Encode.bool operation.deprecated )
-    , Internal.maybeEncodeListField ( "security", encodeSecurityRequirement ) operation.security
+    , operation.security
+        |> Maybe.map (\security -> ( "security", Json.Encode.list encodeSecurityRequirement security ))
     , Internal.maybeEncodeListField ( "servers", encodeServer ) operation.servers
     ]
         |> List.filterMap identity

tests/Test/OpenApi/Operation.elm

@@ -3,7 +3,8 @@ module Test.OpenApi.Operation exposing (suite)
 import Dict
 import Expect
 import Json.Decode
-import OpenApi.Operation
+import Json.Encode
+import OpenApi.Operation exposing (security)
 import Test exposing (..)
 
 
@@ -68,8 +69,22 @@ suite =
         , test "security" <|
             \() ->
                 decodedOperation
-                    |> Result.map (OpenApi.Operation.security >> List.length)
-                    |> Expect.equal (Ok 1)
+                    |> Result.map (OpenApi.Operation.security >> Maybe.map List.length)
+                    |> Expect.equal (Ok (Just 1))
+        , describe "when 'security' is unspecified" <|
+            [ test "it decodes to Nothing" <|
+                \() ->
+                    Json.Decode.decodeString OpenApi.Operation.decode securityUnspecifiedExample
+                        |> Result.map OpenApi.Operation.security
+                        |> Expect.equal (Ok Nothing)
+            , test "it is not encoded" <|
+                \() ->
+                    Json.Decode.decodeString OpenApi.Operation.decode securityUnspecifiedExample
+                        |> Result.map (OpenApi.Operation.encode >> Json.Encode.encode 0)
+                        |> Result.andThen (Json.Decode.decodeString OpenApi.Operation.decode)
+                        |> Result.map OpenApi.Operation.security
+                        |> Expect.equal (Ok Nothing)
+            ]
         , test "servers" <|
             \() ->
                 decodedOperation
@@ -148,6 +163,20 @@ example =
 }"""
 
 
+securityUnspecifiedExample : String
+securityUnspecifiedExample =
+    """{
+  "summary": "Updates a pet in the store with form data",
+  "operationId": "updatePetWithForm",
+  "responses": {
+    "200": {
+      "description": "Pet updated.",
+      "content": {}
+    }
+  }
+}"""
+
+
 failingExample : String
 failingExample =
     """{