dwyl
Document API endpoints
While working on dwyl/smart-home-auth-server#26 I was looking for any API endpoints that could simplify the implementation. There is one API endpoint in the code, but it's request/response structure isn't documented anywhere.
Documenting the API endpoints would be useful for anyone using auth
@th0mas can you please investigate how we can either automatically (generate) API docs using a script or something that requires minimal maintenance? 💭 I'm fine doing the docs a couple of times, but ultimately we want something that is self-updating so it does not rely on people to update when they make changes.
From my previous knowledge of API documentation:
Its possible to generate API documentation but you have to heavily annotate the API code which may not be worth it for our (small) use case.
There is a Swagger implementation for Phoenix: https://github.com/xerions/phoenix_swagger but this seems a bit overkill for our use case.
If we want to expand this API, a proper Swagger/OpenAPI spec is worth looking into
@th0mas OK. in that case we should just do it manually for the handful of endpoints we have and if it grows beyond a certain threshold we may revisit the swagger. We will definitely need to do that research for our "main" app.
But for now most of auth is handled by auth_plug and the only "public" (REST/JSON) endpoint is used by rbac. 💭
To view the /approles/:client_id endpoint, you simply need to copy the first half of your AUTH_API_KEY and paste it into the URL bar in your favourite browser. Open the following sample in Firefox to get JSON formatting: https://dwylauth.herokuapp.com/approles/88SwQGkiif6PuRfpN99No8j7zQZJdTEgedHTGuZpxbxYqsksti2D
e.g:
app_id: null just means this is a default role.
If your App has custom roles then the app_id for your App will appear.
@th0mas in our effort document the API I've created a new file specifically for the external REST API functions: https://github.com/dwyl/auth/blob/9860e3f9e6e4495ff6e50d75a5a5cf1314c7d07c/lib/auth_web/controllers/api_controller.ex#L1-L23
Will be adding the person_roles function to it for #121
Feels like a sane way of managing/documenting our API in the short term. Thoughts? 💭
Running: mix phx.routes gives a summary of the api endpoints, would this suffice @th0mas?
