OpenAPI generator

[System-Glitch]

Proposal

Develop a module able to generate OpenAPI specification for Goyave applications by reading the main route registrer and validation rule sets.

This feature could be included in the CLI Utility ( #39 )

Possible drawbacks

None.

Additional information

This issue is a feature proposal and is meant to be discussed.
It is also a good candidate if you want to contribute to the project.
This should probably be developed as a side-project.

[System-Glitch]

I had a few ideas to make this feature:

• Make it build-in (it would be implemented in a new openapi.go file at the root of the project, to be able to access unexported fields)
• A lot of information can be retrieved simply by reading the route definition and its validation rules.
• The route description can be retrieved using handler comments and godoc.
• The hardest part is not mandatory: getting information about the responses.
• Adding an optional (nullable) struct to the Route struct, containing OpenAPI information that can be added manually, such as potential responses, examples, etc.
• OR adding this information in the handler's comments (using annotation-like syntax like Beego does for example)
  • The go/ast package could be used for comment extraction
• For ease of use, it could be integrated into the CLI utility that is being developed.

[njr8392]

I'd love to help you with this if you have't already started.

[System-Glitch]

Hello @njr8392 ! Thank you very much for your help ! I haven't started this feature yet. Don't hesitate to contact me (via email, telegram or discord) if you have any question or if you need guidance.

[njr8392]

appreciate it!I agree that reading the routes/validation requirements would do the bulk of the job or using godoc to parse comments.  How would you ideally like this implemented? Should i assume that the user will declare routes in a routes.go file? Maybe read all files to look for route declaration/validation and parse that info and put into a document format?  Is your goal solely to produce automatically generated documentationfor the api the user creates?Thanks, NickSent from my Verizon, Samsung Galaxy smartphone -------- Original message --------From: SystemGlitch <notifications@github.com> Date: 10/22/20 2:56 AM (GMT-05:00) To: System-Glitch/goyave <goyave@noreply.github.com> Cc: Nicholas Rodgers <nrodgers88@gmail.com>, Mention <mention@noreply.github.com> Subject: Re: [System-Glitch/goyave] OpenAPI generator (#42) Hello @njr8392 ! Thank you very much for your help ! Don't hesitate to contact me (via email, telegram or discord) if you have any question or if you need guidance. —You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.

[System-Glitch]

• If possible, that would make more sense to me if this was a separate project. I don't want applications in production to waste memory usage holding information needed for the OpenAPI spec generation. Ideally, this is something that we could use in the future CLI app. If it is not possible to get the data you need from outside, we can add an accessor to the Router struct which will copy the route slice.
• Routes should always be defined in a http/route/route.go file so use this as default, but make it so it is possible to optionally give a path to the file.
• Prefer the go/ast package over godoc. Using godoc would be quite hacky.
• I would like to get as much information as possible automatically, but I also want the developer to be able to override and/or complete it. I think Beego's approach with annotations is quite neat. You can take inspiration from it.
• The goal is to turn a Router struct into an OpenAPI specification.

[njr8392]

Awesome, thanks for the clarity. I'll start this and will let you if I have any questions or issuesSent from my Verizon, Samsung Galaxy smartphone -------- Original message --------From: SystemGlitch <notifications@github.com> Date: 10/22/20 2:32 PM (GMT-05:00) To: System-Glitch/goyave <goyave@noreply.github.com> Cc: Nicholas Rodgers <nrodgers88@gmail.com>, Mention <mention@noreply.github.com> Subject: Re: [System-Glitch/goyave] OpenAPI generator (#42) If possible, that would make more sense to me if this was a separate project. I don't want applications in production to waste memory usage holding information needed for the OpenAPI spec generation. Ideally, this is something that we could use in the future CLI app. If it is not possible to get the data you need from outside, we can add an accessor to the Router struct which will copy the route slice. Routes should always be defined in a http/route/route.go file so use this as default, but make it so it is possible to optionally give a path to the file. Prefer the go/ast package over godoc. Using godoc would be quite hacky. I would like to get as much information as possible automatically, but I also want the developer to be able to override and/or complete it. I think Beego's approach with annotations is quite neat. You can take inspiration from it. The goal is to turn a Router struct into an OpenAPI specification. —You are receiving this because you were mentioned.Reply to this email directly, view it on GitHub, or unsubscribe.

[System-Glitch]

After some reasearch, it looks like kin-openapi is the most fitting library we could use.

[System-Glitch]

https://github.com/go-goyave/openapi3