Document API #1865
Comments
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Jan 14, 2023
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 15, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow")
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way. - Fix the small compatibility issues with flaks-restx-1.1.0
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 16, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
FrostyX
added a commit
to FrostyX/copr
that referenced
this issue
Apr 28, 2023
See fedora-copr#1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
praiskup
pushed a commit
that referenced
this issue
May 2, 2023
See #1865 This is still miles from being finished. I tried probably all OpenAPI libraries that are available and decided to go with flask-restx. It is already in Fedora, Packit team uses it as well, and it is malleable enough to be comfortable used within our codebase. I intentionally defined all data types and descriptions in `schema.py` and in the way that everything is defined separately in its own variable. We should IMHO try to compose things as much as possible to avoid copy-pasting. Remains to be done: - Only a fraction of API endpoints are migrated under flask-restx, we need to finish the rest of them - There is a potential to generate WTForms forms or SQLAlchemy models from the API schema or the other way around. - We should share descriptions between API fields and web UI as much as possible - Packit team uses does something like this, we should do as well @koji_builds_ns.response(HTTPStatus.OK, "OK, koji build group details follow") Error responses should be documented the same way.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Original issue: https://pagure.io/copr/copr/issue/1865
Opened: 2021-06-24 16:35:06
Opened by: msuchy
We should document our API. Not just the Python bindings.
This is a good start point. https://stackoverflow.com/questions/36634281/list-of-swagger-ui-alternatives.
I personally like the Swagger most (like this one https://api.studer-innotec.com/swagger/ui/index#!/Installation/Installation_ReadParameter )
But ReDoc or Swagger-UI (the fork) looks good too.
frostyx commented at 2021-06-29 19:12:01:
We should do this, for sure.
Swagger (OpenAPI) seems to be a good choice. I don't have any experience with neither but the usage doesn't seem to be very complicated
https://github.com/flasgger/flasgger#using-dictionaries-as-raw-specs
There is one important thing we IMHO shouldn't overlook. Currently, APIv3 uses our custom forms in
forms.py, that are shared with the web UI counterpart of that API action. We IMHO shouldn't get to the point where API defines its own form definitions and the web UI has its own separate form definitions.We should IMHO migrate both API and web UI to use the same definitions/forms or generate them for one of those from the other.
praiskup commented at 2022-01-10 08:42:27:
The question is whether we can transform the form input into the OpenAPI
input easily. If not, IMVHO we don't have to stick with this dogma. The
current approach is pretty hard to understand, it really caused nightmares
to me.
OpenAPI-like like interface is a good enough reason to start with IMO
api_4, if the api_3 can not stay compatible while moving to OpenAPI.
The text was updated successfully, but these errors were encountered: