[krsyoung]

First, it is too bad that you spent weeks and probably didn't find the "right" solution (because it doesn't seem to exist).

Second, I like your enthusiasm for specs from code ... the problem (opportunity?) today is that the specifications intertwine human readable descriptions / summaries with the actual endpoint / payload information.

I would hate for my devops pipeline to kick-off because somebody fixed a typo in some human focused in-line documentation. I personally don't think it belongs in the code but absolutely agree with the spirit of your comment (if you keep them separate it is more work and they will get out of sync!).

The best luck I have is working within the specification (i.e. Swagger) and avoiding doing things that don't model well. This seems backwards, but for most of the development I've been involved with to date it has served the projects well.

Interested if others have had luck embedding API specs into code.

[ewittern]

Mixing code with documentation is one concern. Another issue is that extracting the information needed to create a Swagger from source code is hard, especially when using dynamic languages (JavaScript, Python). One approach is to use dedicated annotators to relate code with parts of an API spec - but then you have the first problem again...