Request: Include enums

[jleclanche]

While I'm here I might as well follow up on #28 with a long-time request: I'd love for the spec to include all the enums for possible string values everywhere.

This would make this stuff a lot easier:

https://github.com/dj-stripe/dj-stripe/blob/9145410fb4b067e8aad7f181ddc8b339a3514774/djstripe/enums.py#L55

Right now that's all done manually...

[jleclanche]

If openapi provided them reliably then maybe they could even be included in eg. stripe-python.

In general when dealing with a string-based API I don't like hardcoding strings because it's typo-prone in ways that can't easily be caught. A condition such as if source.type == "ailpay" will silently never be true, whereas if source.type == SourceType.ailpay will fail at compile time, runtime or lint-time depending on the setup.

[brandur]

Yes, agreed this would ideal. Unfortunately, our backend (which we reflect the spec out of is) is going to make this feature somewhat difficult :/ I'm going to mark the issue as future given that it's something that should be implemented.

[jleclanche]

While going through the docs I also realized it could help a lot to have documentation for enum values.

Here's an example of what you could do. Current screenshot:

Collapsed state mockup:

Expanded state mockup:

This would help me because I want to get the description for a field without the "Possible values are ...", since that's noise in my use case (the possible values are shown separately).

I imagine that in the spec those possible values and documentation for them would be separated from the description of course. And having documentation for each possible value would also be useful as I could showcase it as a value help text in my admin app.

[brandur-stripe]

Yeah, agreed that would be awesome.

Hm though, for now at least getting this in place would be a fairly sizable odyssey in that we'd have to go back through a lot of code and retrofit quite a few values. Unfortunately, I don't think I'll be able to get that in anytime soon.