search

nitishm / vegeta-server

A RESTful API server for vegeta, a load testing tool written in Go.
MIT License
63 stars 17 forks source link

Add REST API reference documentation #7

Closed nitishm closed 5 years ago

nitishm commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

@hazzabee Sounds great. Looking forward to the updates !

nitishm commented 5 years ago

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

hazzabee commented 5 years ago

@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 commented 5 years ago

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

hazzabee commented 5 years ago

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

nitishm commented 5 years ago

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

hazzabee commented 5 years ago

@nitishm Great, thanks Nitish :)

nitishm commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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?