New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
OpenAPI support #528
Comments
I would say yes, but I would also not want to change the current API version to do this, because it will break thousands of plugins, and that's not how you build APIs.
|
I absolutely agree with you that introducing OpenAPI shouldn't be a breaking change. I think the first step should be introducing the OpenAPI spec only as a manner of documentation of the existing APIs, without replacing anything in the current infrastructure that serves the APIs, nor modifying the APIs themselves. |
Hi @NiccoMlt Does it make sense documenting our current V2 API with OpenAPI? (Even though we are not OpenAPI compliant?) I don't know how OpenAPI works, sry :) Does OpenAPI provide a tool that builds documentation upon an existing API/schema? If so we can try it out and see the kind of documentation it generates. |
Hi @Naramsim, I'll answer in points:
Yes, I think so: for example, it would help with code generation for clients, servers and tests, which I think is good enough 😄.
OpenAPI isn't heavily opinionated, so I don't think PokéAPI is using something undocumentable; I may be wrong tho, I discovered PokéAPI not so much ago, so I don't know the APIs very well...
OpenAPI by itself is only a specification, and it's commonly used in two opposite approaches:
I prefer the first approach, because I think it is much more clear and maintainable, but to try to use OpenAPI with PokéAPI we could use the second approach to have something to start from. |
This repo uses a Django server to serve the APIs; I don't know Python at all, so I may be missing something, but after some researches I can say that there are still no django plugins/middleware/whatever that could be plugged to have a code-first OpenAPI spec generation. Do you know any PokéAPI servers written with some other framework (ASP.NET Core, most modern JVM-based frameworks and nearly all the JS-based frameworks support OpenAPI)? |
Actually we use Django REST Framework, which does have some OpenAPI support in the form of plugins: https://www.django-rest-framework.org/api-guide/schemas/#generating-an-openapi-schema The actual API you're consuming on the web isn't hosted on Django, but that's neither here nor there for generating the docs. |
That's great! What do you think? |
Hi, I tried generating the static schema using the first suggestion from your link using the environment deployed on Docker with the Docker-Compose you bundle; I put the result on this Gist: https://gist.github.com/NiccoMlt/073b18934a6001fc5a2414c590e3b8ba Currently the spec is not valid (apparently, pyyaml doesn't resolve the tuples correctly?) but it is a starting point. |
I think that would be an awesome addition, now that code generation is getting more and more popular be able to create clients to consume this api without having to write "contract" logic would be amazing !!! |
@NiccoMlt Thanks for the static schema, I used that as a baseline spec (and made it valid manually) for generating API clients using openapi-generator https://github.com/cliffano/pokeapi-clients . The main gap at the moment is that the response payload is just strings at this stage. As I'm not familiar with the Python codebase, can anyone suggest how to to best identify the payload model for the endpoint responses? My intention is to convert the model into OpenAPI schema. @Naramsim Here's an example of the generated doc https://cliffano.github.io/pokeapi-clients/api/latest/ using bootprint-openapi. |
This could be an option tfranzel/drf-spectacular |
After asking on Slack about this, I'm opening this issue here on GitHub to check if is there any interest about this.
The OpenAPI Specification (formerly called Swagger Specification until version 2.x) is an open standard aimed to describe RESTful APIs with machine-readable specfication files (with JSON or YAML syntax) which can be used to generate human-readable documentations but also code and tests for clients and servers in different languages (see for example OpenAPI Generator and Swagger Codegen).
I think that if PokéAPI documented its APIs with the OpenAPI standard it would be much simpler develop, test and maintain client libraries and servers. Also, there are the JSON Schemas of each REST resource already, so it shouldn't be too difficult to develop a global specification of the APIs.
What do you think? Is there any interest about providing an OpenAPI specification of PokéAPI?
The text was updated successfully, but these errors were encountered: