search

smallstep / certificates

🛡️ A private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH.
https://smallstep.com/certificates
Apache License 2.0
6.63k stars 432 forks source link

Request: HTTP-API docs. #183

Open Johannestegner opened 4 years ago

Johannestegner commented 4 years ago

What would you like to be added

Documentation for the endpoints for HTTP API.

Why this is needed

The step cli is great, I like it a lot, still, it would (at least for me) be very nice to just use plain ol' http requests to provision certificates. I could go through the Go code and figure all the endpoints out and do it, whilst I think that there are more people than me that would love docs for this.

Is this something that is planned (or in the making)? Else I would like to request this.

dopey commented 4 years ago

Hey, we're stoked that you opened this issue! We discussed documenting the API a while back (because we too like to script against an API, when available) but figured we'd wait until there was some interest from the community.

The most frequent ask from users has to do with tutorials and guides for how to run the CA in different environments. So, with regards to documentation, those are our main focus short term. That said, API documentation is near and dear to our hearts and we'll definitely schedule time for this in the next few months.

And of course, more support for this issue will help us to prioritize :)

Johannestegner commented 4 years ago

Happy to hear that it is in the pipeline! I will take a look at the code and see if I can create a small piece of doc to start of when I have the time! :)

TheSecMaven commented 4 years ago

this is the same issue we are facing, we have some use cases that may require we use the api so having those endpoints documented would be huge, we should use a standard like swagger or even just publish a super awesome postman collection and that would be enough to get people started!

dharanikumar-s commented 4 years ago

I am in need of the same. My client environment approve using only FIPS 140-2 validated crypto modules. Hence i can't run the step cli, since step needs go's native crypto library which is not FIPS validated. It will be helpful if you publish HTTP API doc since i am not new to go language and it will be difficult for me to go through the code and understand myself.

Johannestegner commented 4 years ago

So, I've been really bussy for a while, so not had much time to look into making a small "first version" to allow anyone to pick up on, but got some free time at the moment between contracts, so thought I'd take a look!

My thoughts was to throw together a Swagger api doc project, but seeing I'm not a go-dev, I thought Id ask here first before I start doing it all the wrong way! Go seems to have a whole lot of nice documentation features, which is sweet and all, but I cant seem to find any which is made just for making api code into documentation. I've checked "swaggo", which seems quite nice and all, but basically requires documentation in the code via comments. So, the question: Is there a tool that makes it even easier or should I just start commenting away and create a PR for the docs? :)

LecrisUT commented 3 years ago

Quite late to this issue. The only go poject I know that has some api documentation is caddy. Didn't check if it's manual or automatic. Outside golang, powerdns has a strong api documentation, maybe it also supports golang

mcarbonneaux commented 1 year ago

the api are dev base on go-chi framework. the api router are her.

chi as docgen add on go-chi/docgen that are abel to generate documentation.

the doc gen are abel to generate documentation in raml (swagger like).

but no documentation on the site how to do...

hslatman commented 1 year ago

@dopey it might be nice to define/provide these API docs similar to how we're going to provide them for our product APIs.

@mcarbonneaux I've been trying out the go-chi/docgen package as one way to document our product API, as it looked like a nice way to include the middleware documentation automatically too. I did encounter some minor issues that I can live with for internal docs/debugging purposes, but I'd like our public API docs to be nicer. I haven't tried RAML yet, but I'll have a look to see if it works 🙂

joostdecock commented 8 months ago

I was starting to question my sanity when I was unable to find documentation for the REST API 😂

And of course, more support for this issue will help us to prioritize :)

Consider me supporting this issue. But given that it's 4 years old, what can be done to give this some TLC?

joostdecock commented 8 months ago

For others looking for API docs, this is the closest I've found https://github.com/smallstep/clients/blob/main/postman/step-ca.postman_collection.json