Missing securitydefinition, tags, summary etc.

[dflorey]

We are building the stripe integration for our customers (https://www.ultradox.com) based on the stripe API spec.
It is working to some degree, but it would be very nice to some more info in the spec.
Even if I badly missed the Christmas deadline, here comes my wishlist:

1. Add a security definition and security
   As stripe is using a mixture of basic auth and api key, this would be the perfect declaration for us to auto-generate our integration:

  "securityDefinitions": {
    "apiKey": {
      "type": "basic",
      "x-summary" : "Access your stripe account",
      "x-header-user" : "API Key",
      "x-placeholder-user" : "sk_live_ASasduihgZGAUd342abcd",
      "x-password-supported" : false,
      "x-instructions": "Enter your [stripe secret key](https://dashboard.stripe.com/account/apikeys)"
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
...

2. Tags etc.
   We are grouping the operations based on tags and are also creating the documentation from the spec.
   It would be great to have additional info to be able to generate the docs similar to the stripe docs.
   Example for a complete operation including tags and summary (as it appears in the stripe api reference):

    "/v1/balance": {
      "get": {
        "tags": [
          "Balance"
        ],
        "summary:" "Retrieve balance",
        "description": "Retrieves the current account balance, based on the authentication that was used to make the request.",
        "operationId": "BalanceRetrieve",
...

[brandur-stripe]

Yeah, we should put a security definition in.

Just out of curiosity, do you want the tags mostly so that you can group "like" API methods into a single API resource? (Like exactly how it's shown in the reference documentation? If so, I'm not sure that tags are exactly what we want here given that they can also be used to annotate methods with other information.)

[dflorey]

It would be great if the tags would reflect the "chapters" in the reference documentation.
I think that it is more or less common practice to use the tags as chapter names.
The apiguru guys use the tags in their ReDoc tool to generate the navigation submenus in the same way:
https://rebilly.github.io/RebillyAPI
This is an example of the docs generated from an imported api in our own app:
https://help.ultradox.com/en/reference/api/apifriendsplusme:friendsme:10/users/getidentity.html
So the tags and summary of the operation are used to create a proper nav menu.

[dflorey]

You can test the "chapters" by pasting the stripe openapi spec into the redoc tool:
http://rebilly.github.io/ReDoc/?url=https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec2.yaml
This is a great way to get an idea how the API will show up as result of the openapi toolchain.

[jaumard]

we want to use openApi generator to generate the API for dart/flutter, without tags and mostly securityDefinitions it's not possible or the generated code we'll not work as it will not take into account auth. Tags allow the generator to create multiple api class instead of putting everything into one big file