Provide documentation for v3 API

[chartjes]

In order for the Ecosystem QA team to help with the testing effort, we need documentation outlining the v3 API calls so we can write contract tests for them.

[mythmon]

Documentation exists as an OpenAPI definition at https://normandy.cdn.mozilla.net/api/docs/?format=openapi. I'm not sure of the quality of these docs right now though because the HTML view is broken.

The HTML view is broken because Swagger uses inline scripts to render that page, and our CSP policy break that. I'm working on that issue now.

[mythmon]

The HTML documentation is now available at https://normandy.cdn.mozilla.net/api/docs/

This lists all the API end points on the server, (v1 and v3), but the descriptions are lacking. @chartjes is this enough for you to get started? I plan to add this to the list of documentation I'm writing, but if you need more right now I can move it up in priority.

[chartjes]

That should be enough for me to get started. I will let you know if I am missing anything.

…

On Feb 28, 2019, at 3:35 PM, Michael Cooper ***@***.***> wrote: The HTML documentation is now available at https://normandy.cdn.mozilla.net/api/docs/ This lists all the API end points on the server, (v1 and v3), but the descriptions are lacking. @chartjes is this enough for you to get started? I plan to add this to the list of documentation I'm writing, but if you need more right now I can move it up in priority. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[shell1]

updated link: https://normandy.cdn.mozilla.net/api/v3/swagger/ No one is reading these docs to learn how to use API - so what docs would be useful to answer questions?

more concept documentation? then can use the API docs for many needs. which questions are we repeatedly being asked? Is there an area (like a Normandy FAQ) that answers should be dumped as they are asked? To avoid custom answering each question.

story of how it works - the shape of things... buckets and CDNs, and ____. surface the docs in the repo that hook to github pages.