missing schema from openapi spec

[jmls]

The openbao openapi spec obtained from /sys/internal/specs/openapi is missing a load of schema definitions for both read and write

for example, the cubbyhole read & write

I can start making a list of these (and try to figure out how to add them to the codebase ;) ) but should I create a ticket / PR for each one or a big ticket for them all or a ticket / PR for each area (lilke cubbyhole)

[cipherboy]

@jmls I'm happy with a single issue overall, with checkboxes to track completion. :-)

But yes, we recently came across this ourselves, so I'm happy to help out. I think perhaps a semgrep rule could be used: https://github.com/openbao/openbao/tree/main/tools/semgrep -- but I'm not sure if we have an existing one.

/cc: @fcbajao

[jmls]

so, I'm going to ask for some leeway here - I am a go noob, struggling with bloody & and * 🤣 and go in general

I was trying to fix cubbyhole as a starter, the read and list operations (just a poc to see if I can add responses, the shape is currently not important !)

I added

					Responses: map[int][]framework.Response{
						http.StatusOK: {{
							Description: "OK",
							Fields: map[string]*framework.FieldSchema{
								"keysxx": {
									Type:     framework.TypeStringSlice,
									Required: true,
								},
							},
						}},
					},

to the read operation in vault/logical_cubbyhole.go

and almost the same to the list operation

					Responses: map[int][]framework.Response{
						http.StatusOK: {{
							Description: "OK",
							Fields: map[string]*framework.FieldSchema{
								"keyszz": {
									Type:     framework.TypeStringSlice,
									Required: true,
								},
							},
						}},
					},

built bao, and ran the dev server. Then I grabbed the openapi spec and examined it

sure enough, the read operation now has

"responses": {
            "200": {
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/CubbyholeReadResponse"
                  }
                }
              },
              "description": "OK"
            }
          },
          ```
          
with 

    "CubbyholeReadResponse": {
      "properties": {
        "keysxx": {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },

however, the same cannot be said of the list response. nada. nothing

what am I missing ? why would read work but not list ?

[jmls]

I somehow suspect the kv2 endpoint also does not have responses defined ...

I have always hated the fact that a query parameter can change the whole meaning of an endpoint - so, yeah would also prefer the list to be broken out separately ;)

[cipherboy]

@jmls Does open API allow you to define custom verbs like LIST?

[jmls]

chatGPT says so ;)

OpenAPI, by default, defines a specific set of HTTP methods (verbs) that can be used in API specifications, primarily focusing on the standard methods: GET, POST, PUT, PATCH, DELETE, and OPTIONS. However, it is possible to implement custom HTTP methods in an OpenAPI specification, although this is generally not common practice.

Using Custom Verbs in OpenAPI
Custom Methods: You can define a custom HTTP method in your OpenAPI specification. For example, if you want to define a custom verb like PURGE, you would add it as a key under a path object:

yaml
Copy code
paths:
/example:
purge:
summary: "Custom purge operation"
responses:
'200':
description: "Successfully purged"
This defines a new operation for the /example endpoint using the PURGE method.

Compatibility: While OpenAPI allows for custom methods, not all tooling and libraries that support OpenAPI will handle these methods correctly. Many tools expect the standard HTTP methods and may not provide full support for custom verbs.

Best Practices: It’s generally advisable to stick to the standard HTTP verbs for compatibility and clarity unless you have a compelling reason to use a custom method. This ensures that your API remains predictable and easy to consume.

API Documentation: When documenting your API with custom methods, ensure you provide clear documentation on how these methods behave and under what circumstances they should be used.

[tsaarni]

I stumbled across this thread and out of curiosity I decided to look into it a bit. Disclaimer: I haven’t worked with OpenAPI, so I’m not an expert here. Here’s what I found:

There is a longstanding issue regarding support for more methods, including fully custom ones OAI/OpenAPI-Specification#1747. The latest specification still has a path item object with a fixed methods, which makes me think that the ChatGPT response might be a hallucination. Recently, there has been some activity on the GitHub issue, which might mean changes in OpenAPI 3.2 time frame, however, it seems it may be just adding some popular methods from the IANA HTTP method registry, and support for custom methods may need to wait for bigger revision update of the spec. With this information, I guess LIST cannot be included in standards complying way.

[cipherboy]

Thanks @jmls and @tsaarni!

From that PoV, I don't know what our easy options are to support this. Could we perhaps support generating two OpenAPI schemas, a normal one, and one with just the overridden LIST endpoints? Would there be a way to reconcile that post-client generation and work with dual specs easily?

Thoughts?