Mc issue 356 set up swagger

[maxachis]

Fixes

• Set up Swagger API Docs data-sources-app#356

Description

• Updates backend code to provide detailed Swagger API documentation.
• Adds slight changes to existing tests to account for cases not previously caught.

Testing

• Run all tests in tests directory
• Test Swagger API by either accessing root path of Flask app (if running locally), or on /api path of base url if accessing remote web site.

Performance

• Performance impact marginal.

Docs

• Incorporated within the Swagger API changes.

[josh-chamberlain]

wow, the endpoints and models up at https://data-sources-v2.pdap.dev/api are so nice. It looks like they don't all have properties—how are those generated?

I made a PR in docs: https://app.gitbook.com/o/-MXypK5ySzExtEzQU6se/s/-MXyolqTg_voOhFyAcr-/~/changes/510/api/v2-api-docs-wip

I wasn't sure about removing the homepage search cache stuff, I don't see it in swagger.

[maxachis]

wow, the endpoints and models up at https://data-sources-v2.pdap.dev/api are so nice. It looks like they don't all have properties—how are those generated?

I'm not 100% sure what you mean by properties in this context. However, the general answer to how things are generated is that they are defined within code attached to each Resource as decorators. What parameters are accepted, how they are described, whether they are required, what responses can be returned, all are declared within the relevant Resource class.

In addition, further descriptions can be provided by the docstring for that Resources HTTP methods, and it seems they are amenable to at least some forms of nice-looking formatting (such as bullet points), but I haven't delved too deeply into those.

Anything we want to add or modify to these can be done via changes to the code, at the Resource level.

I wasn't sure about removing the homepage search cache stuff, I don't see it in swagger.

Technically, the homepage search cache endpoint still exists only in v1 and not v2. At the time, we'd developed it just for v1 so we could get it working -- we haven't yet emulated it in v2. Once we migrate it into v2, we can create documentation for it as well!

[josh-chamberlain]

@maxachis I meant the properties shown on the current swagger docs as example responses. Screenshot attached. Your other issue addressed that, though.

re: the homepage search cache, gotcha! I removed it from the gitbook v2 docs.

https://app.gitbook.com/o/-MXypK5ySzExtEzQU6se/s/-MXyolqTg_voOhFyAcr-/~/changes/510/api/v2-api-docs-wip