search

minetest / contentdb

A content database for Minetest mods, games, and more
https://content.minetest.net
GNU Affero General Public License v3.0
95 stars 46 forks source link

OpenAPI spec generation with flask-openapi3 #510

Closed JamesClarke7283 closed 3 months ago

JamesClarke7283 commented 8 months ago

I saw you made a help page for the REST API for ContentDB. https://content.minetest.net/help/api/ Did you know there is a more formal way to document REST APIs?

The OpenAPI spec.

I am mostly making this PR so i can easily make a custom ChatGPT that interfaces with minetests ContentDB. They take a OpenAPI spec as input for the actions, so i though i might as well kill two birds with one stone. Use this so i can integrate contentDB with chatGPT and also help you document your project as well.

Here is the list of endpoints to complete:

This PR adds the following dependencies:

rubenwardy commented 8 months ago

Nice! Yeah, I know about OpenAPI now - just didn't in 2018. Thanks for working on this

JamesClarke7283 commented 8 months ago

Nice! Yeah, I know about OpenAPI now - just didn't in 2018. Thanks for working on this

You are very welcome! Big fan of your work BTW.

The good thing about flask-openapi3 is if the datatypes change, it will update itself, apart from the human text descriptions for what the parameters do. but the actual definitions are autogenerated.

Now ive just got to figure out how to use the SqlAlchemy models as Pydantic models with pydantic-sqlalchemy

JamesClarke7283 commented 8 months ago

Nice! Yeah, I know about OpenAPI now - just didn't in 2018. Thanks for working on this

Could you help me a tad with this PR a tad? whenever i add this to the app/blueprints/__init__.py file, it gives an error.

from app import app as flask_app
flask_app.register_api(bp)

Error:

worker-1    |   File "/home/cdb/app/__init__.py", line 101, in <module>
worker-1    |     create_blueprints(app)
worker-1    |   File "/home/cdb/app/blueprints/__init__.py", line 28, in create_blueprints
worker-1    |     app.register_blueprint(module.bp)
worker-1    |   File "/usr/local/lib/python3.10/site-packages/flask/scaffold.py", line 50, in wrapper_func
worker-1    |     return f(self, *args, **kwargs)
worker-1    |   File "/usr/local/lib/python3.10/site-packages/flask/app.py", line 1299, in register_blueprint

worker-1    |     blueprint.register(self, options)
worker-1    |   File "/usr/local/lib/python3.10/site-packages/flask/blueprints.py", line 384, in register
worker-1    |     raise ValueError(
worker-1    | ValueError: Couldn't import 'app.tasks.celery': The name 'api' is already registered for this blueprint. Use 'name=' to provide a unique name.
worker-1    |
app-1       | Traceback (most recent call last):
app-1       |   File "/usr/local/bin/flask", line 8, in <module>
app-1       |     sys.exit(main())
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 1050, in main
app-1       |     cli.main()
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1055, in main
app-1       |     rv = self.invoke(ctx)
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
app-1       |     return _process_result(sub_ctx.command.invoke(sub_ctx))
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
app-1       |     return ctx.invoke(self.callback, **ctx.params)
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/core.py", line 760, in invoke
app-1       |     return __callback(*args, **kwargs)
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/decorators.py", line 84, in new_func
app-1       |     return ctx.invoke(f, obj, *args, **kwargs)
app-1       |   File "/usr/local/lib/python3.10/site-packages/click/core.py", line 760, in invoke
app-1       |     return __callback(*args, **kwargs)
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 911, in run_command
app-1       |     raise e from None
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 897, in run_command
app-1       |     app = info.load_app()
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 308, in load_app
app-1       |     app = locate_app(import_name, name)
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/cli.py", line 218, in locate_app
app-1       |     __import__(module_name)
app-1       |   File "/home/cdb/app/__init__.py", line 101, in <module>
app-1       |     create_blueprints(app)
app-1       |   File "/home/cdb/app/blueprints/__init__.py", line 28, in create_blueprints
app-1       |     app.register_blueprint(module.bp)
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/scaffold.py", line 50, in wrapper_func
app-1       |     return f(self, *args, **kwargs)
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/app.py", line 1299, in register_blueprint
app-1       |     blueprint.register(self, options)
app-1       |   File "/usr/local/lib/python3.10/site-packages/flask/blueprints.py", line 384, in register
app-1       |     raise ValueError(
app-1       | ValueError: The name 'api' is already registered for this blueprint. Use 'name=' to provide a unique name.

I need that line so it starts registering the Endpoints with OpenAPI. Here are some resources to help:

rubenwardy commented 4 months ago

Do you still need help with this? I thought you resolved it given your commits afterwards