Need for swagger scanner
Swagger code-gen (doc -> code) is a huge project which generates client/server stub for different programming langauges and frameworks. In the same way, there should be a project "swagger scanner"; which would work for different programming languages and framework. It will scan code and generate swagger document in YAML/json file.
Requriments for swagger-scanner
- Wrapper for all open-source tools to generate swagger doc. It would look inside code and generate swagger doc for different programming language.
- User would be able to run swagger-scanner.jar (just like swagger-codegen). Users would not have to depend on build tools to generate swagger doc.
Honestly, I would happy if there is some tool which satisfies second requriement.
You can use Swagger Inspector to generate API specification given an API endpoint (and from there generate the documentation).
If you are looking to use annotation from a specific language there are several libraries available, like:
- Swashbukle for .NET
- swagger-core for Java
and so on...
Swagger inspector is not an open source tool. Also swagger-core only works with Maven/Gradle. It would have been great if there was a dedicated Java class that can scan for annotations and generate swagger document without depending on Maven/Gradle.
Also, swagger-codegen is an open-source and it supports many programming languages. In the same way, swagger-scanner would be a wrapper would generate swagger docs and it would support multiple programming languages. Also, it would not depend on a specific build tool.
Many of the open-sourced swagger projects do not have good document. A document should clearly lay out input, output and procedure to get output.