Sorting by tags?

[jnardone]

The viewer I use groups items by tag; I would like to take my definition file and sort it by the tags value for each path.

Is that possible using this tool? I played around with the online sandbox and could not figure out a way.

[thim81]

Can you give me an example of what would the tags look like and the expected result? Or share your playground?

[jnardone]

  /admin/api/v1/bar:
    get:
      description: |
        You can list the logs by calling this endpoint.
      operationId: getLogs     
      responses:
        '200':
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuditLogResponse_AuditLog'
          description: OK
      summary: List audit logs
      tags:
        - This is second
  /admin/api/v1/foo:
    get:
      description: |
        You can list the possible widgets
      operationId: getThing
      responses:
        '200':
          content:
            '*/*':
              schema:
                type: array
                items:
                  type: string
                  example: 'success:login'
          description: OK
      summary: List widgets for logs
      tags:
        - First goes here

Simply put - these 2 endpoints are out of order. The tags for the first path are alphabetically after the tags for the second.

I'd want all of the paths sorted by the tags value, so that all APIs using those tags are (a) in alphabetical order and (b) grouped together

[thim81]

@jnardone That sounds like a logical use-case, let me explore some options. I'll keep you posted on my findings in the coming days.

[thim81]

hi @jnardone

I'm working on extending openapi-format to allow the sorting of the paths by alphabet or by tag name. I'm looking for a bit of input on how to "configure" it and would appreciate some input from users like you.

How would you envision configuring the order of paths by ...?

My idea was to add "sortPaths" property to be passed along via --sortFile. Since openapi-format works with configs in files, and this new option influences the sorting, it would make sense to extend it like so.

[thim81]

@jnardone

A follow-up question, since "Tags" can have multiple items, the sorting can only be applied by one 1 Tag item. I would propose to take the 1ste item, or do you have other use-cases in mind?

[jnardone]

That is what I’ve been doing manually, taking the first action (get, post, etc) and the first tag of that. On Aug 1, 2024, at 6:15 AM, Thim @.***> wrote: @jnardone A follow-up question, since "Tags" can have multiple items, the sorting can only be applied by one 1 Tag item. I would propose to take the 1ste item, or do you have other use-cases in mind?

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: @.***>

[thim81]

hi @jnardone

I added the option to sort paths alphabetically or by tag, by passing --sortFile with sortPathsBy: tags Readme > https://github.com/thim81/openapi-format/tree/119-sort-path?tab=readme-ov-file#openapi-sort-paths https://github.com/thim81/openapi-format/pull/121

Would this solve your use-case?

[thim81]

hi @jnardone

We just release 1.22.0 of openapi-format, which includes the option to sort paths alphabetically or by tag.

[thim81]

You can play with it at the online playground https://openapi-format-playground.vercel.app/ and select on the left the desired paths ordering.

[jnardone]

@thim81 this looks great. One question, not sure of the right answer.

Should tags be sorted with respect to case, or not?

Should "API" be before "Aaa"? Personally I think it should be case-insensitive but I can see it both ways.

[thim81]

That is a difficult question, since there might be personnel preferences involved.

openapi-format strives for consistency, so currently it will sort like this: "API", "Aaa", "Zebra", "aaa", "zebra" => Example

Which means:

• Uppercase letters are sorted before lowercase.
• Within groups of similar case, strings are sorted alphabetically.

Other options could be:

• Case-sensitive Order: "API", "Aaa", "aaa", "Zebra", "zebra".
• Case-insensitive Order: "Aaa", "aaa", "API", "Zebra", "zebra"

[thim81]

hi @jnardone

Curious if you had some input on the above options?

[jnardone]

Honestly I see it both ways.

To me tags are more case-insensitive so to me I'd want API to be after "Amount" for example but I'm hesitant to say that there should only be one way to do it. I guess I'd rather have it as an option but as a developer I know that all of these choices get complicated.

[thim81]

@miriamgreis, wonder which type of ordering you would expect with cased elements?

[miriamgreis]

@thim81 I'm not sure. I guess I would also prefer case-insensitive as it seems to be more user-friendly. But on the other hand lots of tools use case-sensitive sorting due to the technical implementation. I'm not sure it's really worth changing it or offering different possibilities.

Most viewers also display the tags in the order they appear in the OpenAPI file. It might make sense to consider sorting the paths in the order of the global tags instead of alphabetically by tags. Because tag order might have a relevance as people want to show more general operations first and specialised ones later, so it's probably not necessarily alphabetically.