Document your API properly or use Swagger!

Why not both

Swagger is not an answer

Ideally, you write the swagger, then you write the API. Most of the machine generated swagger is seriously incomplete.

@SortOfTested with that kind of api and skills you probably won’t need swagger at all

@uyouthe
Swagger is just metadata for your users. You could use raml or anything, really. Point being most frameworks that emit swagger and use swagger UI are incomplete for documentation purposes.

@killermenpl
Depends on the implementation, really. Many languages forgo the specialized openapi comment approach and use language-native metadata to perform the document generation. The limitation of this appears when there is unrepresentable data due to inconsistencies in the metadata models (yaml v xmlcomment v jsdoc v annotations v attributes), or the author simply feels that the data point isn't important. The openapi docs even explicitly state that in either the manual documentation case or the approved generative case, extra work is necessary on the part of the user to completely define the document*.

The most basic example is responses. Most runtime generators show the 200 response, but little else. You should specify a response data type and status code for all possible responses.

There's also details like supported media types, description name conflict (.net is particularly bad about this), and anything that isn't resolvable easily like anyOf/oneOf response types, default responses, etc.

* https://swagger.io/resources/...

Couldn't make swagger work the way I wanted so I started working on my own documentation app: https://github.com/endoc/endoc

@screamingwtf
From your GitHub readme:
> Built by Developers for Developers.

Well, it's also documented by developers for developers. 😉 Aside from how to build and start something it's thin on information.

I'd prefer it starting with what it's good for in some detail and how to work with it. That's essential for me to decide if the project is interesting to me.

@VaderNT it's still just on a "personal project" phase to be honest. I'm planning to spend more time on it soon!