[keycloak-dev] REST API documentation

[Stian Thorgersen]

I agree, generating is best, but we'd need to least figure out how to add missing protocol endpoints, and also exclude internal endpoints.

----- Original Message -----
> From: "Bill Burke" <bburke at redhat.com>
> To: keycloak-dev at lists.jboss.org
> Sent: Friday, 27 March, 2015 1:13:18 PM
> Subject: Re: [keycloak-dev] REST API documentation
> 
> IMO< continue doing it this way for a few more months.  Docs will get
> out of sync fast with REST api.  Which is why it is automated in the
> first place.
> 
> On 3/27/2015 6:58 AM, Stian Thorgersen wrote:
> > Currently we're generating the REST API documentation automatically.
> > There's a few issues with that approach:
> >
> > * Dynamic endpoints are not included (for example openid-connect and saml
> > endpoints are missing)
> > * No categories - we should split docs into admin, openid-connect, saml,
> > etc.
> > * Includes private endpoints - for example required actions and account
> > management are included even though they are not intended for public use
> > * JSON objects not defined - a lot of REST APIs include examples on how to
> > use, including details on the JSON consumed/produced
> >
> > Is there a way to solve this with the current approach or would it be
> > better to manually create the documentations?
> > _______________________________________________
> > keycloak-dev mailing list
> > keycloak-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/keycloak-dev
> >
> 
> --
> Bill Burke
> JBoss, a division of Red Hat
> http://bill.burkecentral.com
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev
>