Add REST API reference documentation

[nitishm]

Create a REST API doc for the backend server built using gin-gonic.
Might consider looking into https://github.com/swaggo/gin-swagger or any other alternatives.

[hazzabee]

Hello @nitishm I've been teaching myself REST API documentation the last 3 months, and would love to contribute if possible? Please direct me to the right files and I'll get started!

[nitishm]

@hazzabee Awesome. You can dive straight into the code. The layout is as follows,

• (/cmd/server)[https://github.com/nitishm/vegeta-server/blob/master/cmd/server/main.go] contains package main which is the entry point to the code. (for the most part this shouldn't be of concern for the documentation)
• (/models)[https://github.com/nitishm/vegeta-server/blob/master/models] is where all the _request.go and _response.go files include the API request and response params (the json notations are added to the structure member tags). This should provide a good idea of what the body params and response bodies look like.
• (/internal/endpoints)[https://github.com/nitishm/vegeta-server/tree/master/internal/endpoints] is where all the endpoints (and their handler logic) are defined.
  (endpoints.go)[https://github.com/nitishm/vegeta-server/blob/master/internal/endpoints/endpoints.go] would be of special interest for the documentation, since it defines the actual REST API paths and register them with the server (see https://github.com/nitishm/vegeta-server/blob/master/internal/endpoints/endpoints.go#L22-L42)
  In the remaining files under the /internal/endpoints you will find the query params (since there are not predefined in the registration step).

I havent thought of how we should capture the REST APIs (code-gen, using gin-swaggo vs manually documented). But whatever be the case I would love to reduce manual effort, since the API might change, and more endpoints will be added in the near future. Some kind of automation would be good.

With that said I am open to ideas !! Let me know what your thoughts are and once we have consensus, you can get started !
The API list is pretty small at the moment but I plan to add a lot more, once the front-end project begins.

Thanks again for picking up this ticket ! Feel free to ask me any question. If communicating via comments is hard, you can pass me your slack handle and I can add you to the (slack)[vegeta-server.slack.com] channel.

[nitishm]

I also want to move all the REST API usage documentation from the README.md to a better place. Would clean out that page a lot and make it more readable.

Once we get this doc started, would be nice to create another usage doc as well.

[hazzabee]

@nitishm thanks for all the above info, that's really helpful!

Re: capturing the APIs, I was going to start documenting in either Swagger Editor or Spotlight (YAML/JSON), as this would make it easier to add new endpoints when they come up. Shall I start with one of those?

And just to check, there are 6 current endpoints?

	v1.POST("/attack", e.PostAttackEndpoint)
	v1.GET("/attack", e.GetAttackEndpoint)
	v1.GET("/attack/:attackID", e.GetAttackByIDEndpoint)
	v1.POST("/attack/:attackID/cancel", e.PostAttackByIDCancelEndpoint)
	v1.GET("/report", e.GetReportEndpoint)
	v1.GET("/report/:attackID", e.GetReportByIDEndpoint)

[nitishm]

@hazzabee Both swagger and spotlight sound ok to provide a static API document.

I wanted to ask about your experience level in Go. If you have previously worked with the language, it would be great if you could explore https://github.com/swaggo/gin-swagger. It is a middleware component, that generates the same swagger spec from comments on the endpoint methods.

My thought is that, even if you are not that experienced with Go, you could possibly follow the gin-swagger docs, to add swagger format comments to the required functions, and then I can help integrate the dynamic doc generation and endpoint to serve the swagger document.

And just to check, there are 6 current endpoints?

Yes these are the only supported endpoints, at the moment.

Let me know what you think. If you feel like you are up for gin-swagger, that would be great. If not we can still create the spec in swagger editor and I can help port the blocks over from the doc to the comments.

[hazzabee]

@nitishm Thanks for the info.

No, I'm afraid I haven't got experience in Go yet, but it looks interesting! It's probably best I create the documentation in swagger editor first, and then explore gin-swagger and see if I can integrate some of those format comments you talked about.

[nitishm]

@hazzabee Sounds great. Looking forward to the updates !

[nitishm]

@hazzabee how is the documentation coming along? Let me know if you need any help.

[hazzabee]

@nitishm Hey! It's going well, just having a bit of trouble with the Reponses object. I don't have Slack yet, would I be able to drop you an email?

[nitishm]

@hazzabee sure. My email is nitish.malhotra@gmail.com. Feel free to shoot me a message.

[hazzabee]

@nitishm Thanks. Did you get my email? It should have come through last week.

[nitishm]

@hazzabee I did get the email. Will try to get back to you by the end of the weekend with my suggestions. Thanks.

[hazzabee]

@nitishm Great, thanks Nitish :)

[nitishm]

Meanwhile I have this outdated swagger spec. It does not match the current implementation but it will give you an idea of how to format the request and response objects
https://app.swaggerhub.com/apis/nitishm/restful-vegeta-oas2/1.0.0
its written in OpenAPI 2.0 instead of 3.0 that you are using. So the syntax might be a little different.

Hopefully it helps.

[devonapple]

I saw this item was closed - have the documentation needs for this program been satisfied? I am also looking for something to help document.

[nitishm]

@devonapple We did add the API references to the doc directory, but are still lacking a more programmatic/automated way of generating the REST API doc. Would you be willing to try out https://github.com/swaggo/gin-swagger ?

[devonapple]

Thank you for your reply! I had a look at a few video tutorials and some documentation, and I am confident that the gin-swagger interface is just outside of my current abilities: I would definitely need some guidance in order to be productive with it. I may need to level up a few times!

[devonapple]

Hi, @nitishm! I have learned more about Swagger, and I would be happy to give this a try, if it is still open!

How much Go would I need to know?