Feature request: Add option to generate one markdown file per swagger tag

Widdershins seems to assume that you have only one Swagger/OpenApi-File which contains the whole API specification and generates a single markdown file from that.

It would be nice to be able to split the result into multiple files (which can then be referenced via the Slate “includes” option) as this would easy maintainability and allow to reuse the generated markdown in other contexts. Also it may help in cases where the final markdown file should contain manually created includes (i.e. content that is not originally maintained in the swagger/OpenApi specification).

What I have in mind is an additional option, that for example results in the generation of one markdown file per swagger-tag (https://swagger.io/docs/specification/grouping-operations-with-tags/). For example if you have:

  /pet/findByStatus:
    get:
      summary: Finds pets by Status
      tags:
        - cat
      ...
  /pet:
    post:
      summary: Adds a new pet to the store
      tags:
        - mouse
      ...

This would generate three files:

• One main “index.md” which has includes for the generated files “cat.md” and “mouse.md”.
• The file “cat.md”
• The file “mouse.md”

Maybe there are also other criteria by which the content should be split, but using tags would fit our use case.

[MikeRalphson]

If you don’t plan any direct support for includes (for the reasons you listed above), this issue can be closed from my side as the workaround works.

I’m not opposed to adding a third method (!) for includes, but I don’t think I can see how they can be incorporated in the stock templates when they’re not known in advance.

Feel free to re-open that discussion at any time, but let’s close on the idea of generating multiple .md files per tag for now.

[geld0r]

Sorry, this got lost. Yes I did try this out and added includes in “main.dot”, like this:

<%= partial "includes/yourFileName.md" %> This makes use of Middleman partials. Our source file is now a index.html.md.erb (yes, really), but includes work this way. The downisde is that (as you said) we had to override the stock templates. This makes version updates quite tricky as one has to take care of merging the changes. Apart from that, this solution works fine.

If you don’t plan any direct support for includes (for the reasons you listed above), this issue can be closed from my side as the workaround works.