Thanks! I still have to open a great deal of issues. Slowly progressing 😄

I thought I could add some of v3 features (including this) to v2 through extensions, but 0.4.0 has already taken an awful lot of time. I'm now moving this to 0.5.0.

I'd like to work on this, but I don't understand how we could add this to v2 so that e.g. swagger-ui could process it just like it would in v3. Do you have some hints on how to get into this?

I'm really happy to hear that you want to work on this, but I only have one solution as of now, and I think it's gonna be a lot of work.

The problem is that we can't add this to v2 directly. My plan is to make use of extensions in v2 (fields of pattern ^x-* are allowed throughout the spec) to support features introduced in v3. Paperclip (codegen and plugins) will understand these extensions. This way, we can still do everything in v2 and convert to v3 whenever we want (including the time when we host the spec in the actix-web app instance). Swagger UI will process the spec emitted in v3. The work involved is more on the v2-v3 conversion, which is why I moved this to 0.5.0.

Ah, so as a first step we need v2 to v3 conversion in general? I couldn't find an issue for v3 yet (except the v3 to v2 conversion for codegen, which seems mostly orthogonal?)

Yes, there wasn't an issue until now. #177 😅

Even though OpenAPI doesn't have proper enum support (it only supports simple enums with known values), swagger does support an array of enums (through items field). For example:

{
  "definitions": {
    "MyEnum": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "a": {
              "type": "integer"
            },
            "b": {
              "type": "string"
            }
          }
        },
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    }
  }
}

#[serde(untagged)]
enum MyEnum {
    MyEnumItem1 { a: i32, b: String },
    MyEnumItem2(String),
    MyEnumItem3(Vec<String>),
}

Update: I was wrong. v2 doesn't support this.

We could encode single element enums as array of enums with a single element. Better than no support at all, right?

No, because that doesn't respect swagger schema and the spec emitted by us may be misinterpreted by other language-specific tools (including the official Swagger UI). So, it's actually better to have no support rather than having something ambiguous or something that misrepresents user API. That said, we "can" make this work by using vendor extensions, so that paperclip understands this in swagger (v2) spec and when we move to v3, we can use the extensions to emit the corresponding spec in v3 😅

So if I understand this correctly, paperclip only works with OpenAPI 2 at this moment, and that's why we can't do this yet?
Anything I can do to push this forward?

Yeah, we can't do this at the moment because v2 doesn't support it. We'll need v3 (which will be part of 0.5.0 release). If you have spare time to work on v3, then I'm happy to help! 😄

Yes I can make some time for this

This issue isn't specific to actix-web plugin is it?

It is. For now, we only have actix-web plugin. When we support other frameworks in the future, we can open related issues.

Just to verify my understanding of the code, isn't this more about what the general proc-macro machinery can do? Functionality has to propagate to actix-web plugin of course but still.

The proc macros that we have right now implement the traits exposed by the plugin, so they are specific to actix web. Am I addressing this correctly?

Sorry, so far I have only a shallow understanding of the code base. I thought that there was some more general functionality, then the actix layer just being sort of a thin adapter. I'll acquaint myself more with the code.

No worries! Feel free to ask as many questions as you like! I was just wondering whether I understood and addressed the question correctly. 😅