[batch] Openapi doc for batch service

[cjllanwarne]

Change Description

Adds two endpoints in the batch service hosting an openapi specification and a swagger page.

Note to reviewers: The API specification documentat itself is nice to get right, but relatively low risk. I'd prioritize time making sure the framework to host it is correct, and the openapi setup sections before scanning through the details of every individual API call.

Security Assessment

Delete all except the correct answer:

• This change has a high security impact
  • Required: The impact has been assessed and approved by appsec

Impact Description

We are adding two new endpoints in batch. Mitigating factors:

• There are no user parameters for these endpoints
• The pages being hosted are mostly static, apart from the "base url" which the API documentation and swagger page targets, which is generated in the backend.

(Reviewers: please confirm the security impact before approving)

[sarahgibs]

I've checked that ZAP will ingest this version of the openapi spec, and doesn't have any problems with it. Thanks for adding these endpoints.

[patrick-schultz]

I can't really comment on the endpoint docs themselves, but I do have one suggestion about the metadata setup.

[patrick-schultz]

This could be a bit of a pain to keep updated. It's also not technically correct, since changes to the service api are deployed continuously, not when we release a new version. Does this actually matter much?

Actually, I think we could template this. front_end.py already imports version, which is the full hail version, including the commit hash. That would be most accurate. But if you think we'd rather have just the release version, you could also import pip_version from hailtop.

[cjllanwarne]

Hmm, good catch. This is not really necessary, at least for the purposes of this POC. I think if we were publishing multiple versions of our API spec we might want to be able to switch between or identify which one we're looking at, but that's definitely not a now requirement. For now I'll just remove this field since it's already out of date.

[cjllanwarne]

ah, it's a required field. I'll just template in the version