Pokeapi: OpenAPI support

[NiccoMlt]

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?

[phalt]

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.
So either:
1) a new version that is based on the OpenAPI spec
2) A flag/parameter/http header that can be set to change to the OpenAPI spec

[NiccoMlt]

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.
The specification should be fully built (and possibly tested against current tests) before even thinking about using it to introduce breaking changes.

[Naramsim]

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.

[NiccoMlt]

Hi @Naramsim, I'll answer in points:

Does it make sense documenting our current V2 API with OpenAPI?

Yes, I think so: for example, it would help with code generation for clients, servers and tests, which I think is good enough :smile:.

Even though we are not OpenAPI compliant?

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...

Does OpenAPI provide a tool that builds documentation upon an existing API/schema?

OpenAPI by itself is only a specification, and it's commonly used in two opposite approaches:

• Design-first, in which the OpenAPI spec is used with some build tool to generate the server code for the documented API, along with model classes and tests;
• Code-first, in which an OpenAPI spec is generated either build-time or run-time from the API defined on a server in the traditional way.

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.

[NiccoMlt]

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)?

[phalt]

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.

[NiccoMlt]

Actually we use Django REST Framework, which does have some OpenAPI support in the form of plugins

That's great!
This plugin should be able to be used to generate a valid specification to test the ground and potentially start from!

What do you think?

[NiccoMlt]

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.