docs: add openAPI spec, add nix-shell

[Indyandie]

• Adds the ability to generate an OpenAPI document using drf-spectacular package.
  • Starlight OpenAPI
  • Stoplight Elements
• Adds nix-shell support via the defaults.nix.

To generate pokeapi OpenAPi document run:

./manage.py spectacular --color --file openapi.yml

To start the nix-shell run:

nix-shell

Fixes #528

[Naramsim]

Hi, what's nix shell? And what's the added advantage of using it?

[Indyandie]

Hi, what's nix shell? And what's the added advantage of using it?

Howdy @Naramsim!

The nix-shell is an interactive shell that's created using a nix expression (in this case the default.nix). It allows you to create a project specific dev environment by running nix-shell. If done correctly it will install all the necessary programs required for the project.

The advantage is optional for most, but it let's anyone who uses nix to run nix-shell to have a local dev environment ready to go with little to no setup. This was a requirement for me because I'm running NixOS, and working with python is tricky due to the nature of the system.

[GreatNovaDragon]

As i read this, its nix-shell is nothing that is needed, but nice to have and nothing that hurts to be included for the convenience of developers on NixOS

[Naramsim]

Hi! Thanks for all the commits! When you are ready and the tests are passing you can ping me or request a review

[Indyandie]

@Naramsim this is ready to go!

[Naramsim]

Ok thanks! Maybe @ryu-0729 can also review this. I'm really unsure which PR should I merge in, tbh. Both of you have made a great work

[Indyandie]

Thanks @Naramsim! @ryu-0729 a review will be much appreciated 🙇

[ryu-0729]

@Indyandie @Naramsim
I have reviewed it.
The way you divided the tags and set up the schema was very helpful.
I have added a comment and whould be happy if you could check it out.

Thanks.

[ryu-0729]

Some retrieve APIs allow passing name as a path parameter.
I was thinking that a string would be better than an integer, but what do you think?

It can be defined by overriding the retrieve method of PokeapiCommonViewset.

    @extend_schema(
        parameters=[
            OpenApiParameter(
                name="id",
                description="This parameter can be a string or an integer.",
                location=OpenApiParameter.PATH,
                type=OpenApiTypes.STR,
            ),
        ]
    )
    def retrieve(self, request, pk=None):
        return super().retrieve(request, pk)

[Naramsim]

Yes, we can treat IDs like strings

[Indyandie]

@Naramsim @ryu-0729

• Starlight OpenAPI
• Stoplight Elements

[Indyandie]

@Naramsim @ryu-0729 I put together a mockup of the pokeapi.co using this OpenAPI document and astro starlight.

[Indyandie]

TODO: review https://github.com/tfranzel/drf-spectacular/releases/tag/0.27.2

[Naramsim]

Hi! Are you still here? I got back for a while!

I think I'll merge this PR since it's too long we have it open. Honestly, I couldn't decide which one to merge and I decided to go with @Indyandie one since he seems a bit more active on GitHub than @ryu-0729 (in no way I'm criticizing your work or your profile).

[Indyandie]

@Naramsim still here 🙋‍♂️

Let me know if we need anything else to merge. Probably need some instructions in the README?

[Naramsim]

I'll merge this otherwise another 3 months will pass :)

What kind of info do you want to include on the README? I'd put this command in the Makefile.

./manage.py spectacular --color --file openapi.yml

I was thinking that maybe we can also link the openapi.yml over at pokeapi.co

[pokeapi-machine-user]

A PokeAPI/api-data refresh has started. In ~45 minutes the staging branch of PokeAPI/api-data will be pushed with the new generated data.

The staging branch will be deployed in our staging environment and the entire API will be ready to review.

A Pull Request (master<-staging) will be also created at PokeAPI/api-data and assigned to the PokeAPI Core team to be reviewed. If approved and merged new data will soon be available worldwide at pokeapi.co.

[pokeapi-machine-user]

The updater script has finished its job and has now opened a Pull Request towards PokeAPI/api-data with the updated data.

The Pull Request can be seen deployed in our staging environment when CircleCI deploy will be finished (check the start time of the last build).