search

mozilla / normandy

Firefox recipe server
https://wiki.mozilla.org/Firefox/Recipe_Server
Mozilla Public License 2.0
55 stars 46 forks source link

Provide documentation for v3 API #1761

Open chartjes opened 5 years ago

chartjes commented 5 years ago

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

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

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

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 notifications@github.com 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 commented 5 years ago

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.