Support documenting paths and parameters about createapi HOT 7 OPEN

You’re right, it looks like only entity documentation is supported right now, but adding it for paths and parameters would make total sense!

I think it’s probably a bit tricky, because we can generate paths in multiple styles, but still it would be good to have 🙂

I’ll label this as an enchantment and dig a little deeper when I get some time, thanks for raising!

from createapi.

Starting with Xcode 14, DocC is the best option for generating documentation. But you don't need to do anything to support it (as long as the documentation comments are there). But ideally, you'd want to provide DocC extension files to make logical groups of APIs.

from createapi.

Interesting... If you comment out all of the options under comments in your config file, does it make any difference?

I thought that it might be related to -s, but that doesn't seem to impact any of the fixtures: https://github.com/CreateAPI/CreateAPI/blob/main/Tests/CreateAPITests/Expected/petstore-split/Sources/Entities/Pet.swift

from createapi.

Never mind, I cloned your repo and it didn't make any difference.

I had a glance at the App Store Connect Schema and I can't actually see any title or description fields defined for the component schemas (entities). Can you point me to a specific example of an entity that you are expecting to be documented? I didn't dig too deep so might have missed something

from createapi.

Right, I see! Does that mean CreateAPI only support entity documentation?

I expected these examples:

, {
          "name" : "include",
          "in" : "query",
          "description" : "comma-separated list of relationships to include",
          "schema" : {
            "type" : "array",
            "items" : {
              "type" : "string",
              "enum" : [ "offerCode" ]
            }
          },
          "style" : "form",
          "explode" : false,
          "required" : false
        }

Containing a description:

"description" : "comma-separated list of relationships to include",

To be used to fulfill documentation 🤔

from createapi.

@liamnichols awesome, I think it would be a great addition! Let me know if you need any more feedback or info to get started 💪🏼

from createapi.

While this discussion was originally about the comments in the schema for Swift generation, I think that also providing the option for a markdown file would be a good way of documenting the paths as well. For very, very, very large schemas can be a lot easier to reference, especially when they're grouped together and you can search on the page.

As an example, here are all my paths documented by the OpenAPI generator: https://github.com/jellyfin/jellyfin-sdk-swift/blob/main/README.md

It would suffice to provide the sourcery templates that can parse the generation. OpenAPI also generated markdown for objects but I personally don't care for those.

from createapi.