OpenAPI construction

[c-wygoda]

Related Issue(s):

Description:

• Use standard FastAPI OpenAPI builder and inject metadata through env settings
• Remove stac_api.api.app:StacAPi.customize_openapi method as it unnecessarily wraps the FastApi.openapi call.

PR Checklist:

• Code is formatted and linted (run pre-commit run --all-files)
• Tests pass (run make test)
• Documentation has been updated to reflect changes, if applicable, and docs build successfully (run make docs)
• Changes are added to the CHANGELOG.

[geospatial-jeff]

@c-wygoda Whats the reason for this change?

[c-wygoda]

We want to be able to specify more of the OpenApi metadata fields and in the process I found the customize_openapi method to be a rather redundant wrapper around the OpenApi functionality, if the FastAPI params are used directly in the attribute definition of the app.

[c-wygoda]

This would also tackle #454 if I'm not mistaken.

[geospatial-jeff]

I found the customize_openapi method to be a rather redundant wrapper around the OpenApi functionality,

I agree, this code is leftover from years ago before this project was open sourced when customization of OpenAPI was less flexible. Now customize_openapi is hurting more than it helps (ref #454).

We want to be able to specify more of the OpenApi metadata fields

There is precedence to define openapi related things in ApiSettings so I think this is a good approach 👍

Note to self that at some point in the future we should deprecate StacApi.title, api_Version, and description (obviously a breaking change).

[c-wygoda]

Thanks. I'm happy to help as I'm responsible for an instance, so hopefully can contribute more. Direct feedback welcome as I slowly learn the ropes of this project...

[geospatial-jeff]

@c-wygoda The changes LGTM but I do want to play with this a little more before we merge to understand the difference between setting servers to self.app.servers compared to pulling from the environment within the context of #454 #489 #497

[c-wygoda]

How can I help to move forward? More test coverage?

[gadomski]

@geospatial-jeff ping

[vincentsarago]

@jonhealy1 I think we should use this instead of #639 (we would need to update the landing page)

[vincentsarago]

I'm not 💯 what we should do.

This kinda breaking change so definitely something we should keep for 3.0, but at the same time #639 does almost the same thing without breaking anything.

Both PR fixes stuff but do not represent the best solution to the issue:

• 499: fixes the OpenAPI but does not forward title, description,... to the landing page
• 639: add info to both the OpenAPI and landing page but doesn't use the Config class and add some code duplication

IMO we should wait after 2.5 to be released and see if we can refactor a bit to accommodate both changes

cc @jonhealy1

[m-mohr]

This PR should add some documentation how to set the env variables...

[vincentsarago]

in #639 we implemented part of the proposed solution, Let's wait after 2.5 release to finish this PR