No way to remove a top-level security declaration with an empty array on an operation

[jez9999]

In OpenApiOperation.cs, the documentation for Security states that "To remove a top-level security declaration, an empty array can be used.". Great - this is exactly what I want. To declare top-level security and then remove it for a few operations that allow anonymous access.

The problem is, I can't actually see any way to get OpenAPI.NET to write out an empty array. Both the SerializeAsV2 and SerializeAsV3 methods write out the security section using writer.WriteOptionalCollection(...), which only writes out if (elements != null && elements.Any()). That means that whether you set Security to null or an empty list, the security section will be skipped altogether instead of serialized to an empty JSON array.

I need to serialize it to an empty JSON array, so what should I do? Does there need to be an update to OpenAPI.NET to allow this? Seems to me that there does.

[darrelmiller]

Thanks for reporting this. Agree this is a bug. I will add this to the 1.2.4 milestone.

[jez9999]

@darrelmiller Should this issue be closed if it's not yet fixed?

[jez9999]

@darrelmiller I still don't understand why this is closed when it hasn't been fixed.

[darrelmiller]

@jez9999 My apologies, I was sure that I had replied to this, but I can't find my reply. An empty array is not sufficient. It needs to be an array with an empty object. Here's an example that demonstrates:

openapi: 3.0.0
info: 
  title: Test anonymous operations
  version: 1.0.0
paths:
  /:
    get:
      security: [ {} ]
      responses:
        200:
          description: asdadasd
security:
 - apikeyScheme: []
components:
  securitySchemes:
    apikeyScheme:
        type: apikey

[jez9999]

@darrelmiller But doesn't that indicate optional security, as opposed to the empty JSON array which indicates no security (a purely anonymous operation)?

[darrelmiller]

The array with just an empty object indicates that there is only one security scheme applicable and that scheme allows anonymous access. You are correct that the specification indicates you can use an empty array to effectively eliminate the global security requirement. The result of that is to say "I'm not telling you what the security requirements are". I'm not sure how useful a concept that is.

If your goal is to enable anonymous access then the array with the empty object is the correct choice in my opinion.

[jez9999]

@darrelmiller I don't know where you got the idea that it says "I'm not telling you what the security requirements are". It says "there are no security requirements for this operation". ie. it's not just optional security, there's no semantic reason to provide security for this operation and therefore there is no security scheme specified.

As an example, a system might have mandatory security for user management operations such that only admin users can perform them. It might have optional security for posting feedback, where if the user passes in valid security info, the feedback can be tied to that user, but anonymous submissions can also be given. And it absolutely might have completely anonymous operations like getting build info, or getting weather information, or something where not only do you not have to provide security info, it never makes any sense to do so. I think that's a valuable semantic to express as part of the API spec, and it's why the empty array option exists.

[darrelmiller]

Optional security is described using multiple schemes. i.e.

security:
  - {}
  - myapikey: []

If you want to only describe anonymous access then only provide that scheme.

security:
  - {}

Having said all of this, the reason I said that an empty array says "I'm not telling you what the security requirements are" because OpenAPI descriptions are based on the concept of Open World contracts. An OpenAPI description tells you what you CAN do. It does not tell you what you CANNOT do. You cannot make assumptions about something not being supported in an API because it is omitted from an OpenAPI description.

The clearest example of why this is, relates to status codes. Due to the layered nature of HTTP a client must never assume that the only HTTP status codes that could be returned are the ones listed in the OpenAPI specification. Proxies would always make that assumption invalid.

This is one of the fundamental differences between OpenAPI and WSDL.

[jez9999]

If you want to only describe anonymous access then only provide that scheme.

security:
  - {}

If that's the way to do it, why does the spec even allow you to specify an empty array?

https://swagger.io/specification/#fixed-fields-8

"To remove a top-level security declaration, an empty array can be used."

Having said all of this, the reason I said that an empty array says "I'm not telling you what the security requirements are" because OpenAPI descriptions are based on the concept of Open World contracts. An OpenAPI description tells you what you CAN do. It does not tell you what you CANNOT do. You cannot make assumptions about something not being supported in an API because it is omitted from an OpenAPI description.

By that logic, OpenAPI is never "telling you what the security requirements are" because there might be some additional requirements that it fails to mention. Your argument here seems rather obtuse, I'm afraid. The fact is that in practice, 99.9% of the time, the API is going to require the security given in the OpenAPI definition and not anything else. An empty array will mean "this API operation does not have any security and may only be accessed anonymously". To argue otherwise is rather misleading, I think.

The clearest example of why this is, relates to status codes. Due to the layered nature of HTTP a client must never assume that the only HTTP status codes that could be returned are the ones listed in the OpenAPI specification. Proxies would always make that assumption invalid.

So, nothing to do with the security then.

Be honest (I don't mind what the answer is here, I'm just curious): are you putting up so much resistance to allowing OpenAPI.NET to spit out an empty array here because the way the codebase has been written makes it difficult to do (an empty array is currently interpreted as "omit the security node altogether"), or because you genuinely think there's no reason you'd ever want to output the empty array in the JSON, even after reading the specification?