Add REST API documentation

[nomike]

Add better generated documentation for the REST API.

[achosam]

Hello, My name is Samuel, and I'll like to contribute to you REST API documentation.

Thank you

[nomike]

Hello achosam,

It's great that you would like to contribute to the API documentation.

I just merged a small pull request to add a Makefile which auto-generates an Open API Specification Document in the project's static folder.

It is very basic, but it could serve as a starting point.

A few issues I can see on first look:

• The title of the API is hard-coded in the Makefile and it might be a good idea to parametrize this, what do you think?
• The API version number is hard-coded in the Makefile. It needs to be stored somewhere else. Are there any common practices to ensure that the incrementing of the API version is not forgotten if the API changes (at least the patch version)?
• The definition of the individual endpoints might not be complete (e.g. there are no descriptions). As the OAS document is auto-generated, the missing info need to be added to the code so that the auto-generation picks them up accordingly.

I think the best way for you to contribute would be to fork the code and send me a pull request.

Let me know, if you need anything.

[Ifedolapo-9]

Hello there, I will love to contribute. Hope that's fine.

[nomike]

Sure. If you have questions, just ask. And I'm happy to reviewing your pull requests.

[achosam]

Hello, I saw your reply and I'm happy to be part of this project. Hello @ojo ifedolapo, if you don't mind, we can work together on this project. My WhatsApp number is +234-08057923624

On Thu, Aug 10, 2023, 2:42 PM nomike @.***> wrote:

Sure. If you have questions, just ask. And I'm happy to reviewing your pull requests.

— Reply to this email directly, view it on GitHub https://github.com/nomike/Bauteilsortiment/issues/97#issuecomment-1673250415, or unsubscribe https://github.com/notifications/unsubscribe-auth/BBKIMMKNW6B7ZTWMVMBZN7TXUTQMVANCNFSM6AAAAAAYQ2JORE . You are receiving this because you commented.Message ID: @.***>

[Ifedolapo-9]

Yes, it's a good idea to parametrize the API title in case of future modifications and easy accessibility.

[Ifedolapo-9]

Hello nomike, Hope you are doing great.

I have a few questions.

1. Do you mind if I send the pull requests in stages (i.e per issue resolved in the docs)?
2. http://bts/api/v0 is the base url for every endpoint right?
3. Do you plan to use another website to hold conceptual docs like (User guides and How to sections) or you plan to use swagger only for your docs?

[nomike]

Hi @Ifedolapo-9,

great that you want to help as well.

To answer your questions:

1. Separate pull requests are fine. The only condition is, that none of the tests are failing and that the code could be deployed.

2. This is my first Django application. I do have experience with Python and Flask though (https://nomike.com is a flask application). I was thinking of dropping the "/bts" prefix on the URLs to make them shorter. After all what´s the point. I haven't had time yet though, to try and figure out how. But apart from this, the rest of the path should be "/api/v0¨. The "/api" separates the API from the GUI and the "/v0" should allow for future versions which are not backwards compatible. Let me know what you think of this.

3. Swagger will merely be a tool for documenting the API. The intention here is to give people who want to interface with the API an overview of all endpoints and their capabilities. A few short examples would be nice. And maybe, at some point, SDKs for various programming languages could be added. The data model will change over time, new models will be added, they will gain new attributes, etc. as the software grows. This will also require changes to the API.

I'm trying to use a single-source-of-truth approach wherever possible. For example I define the models in bts/models.py and the views, URLs, serializers, admin pages, etc. are all generic and auto-generated. So if I add a new model in models.py ideally there should be nothing left to do (for URLs, serializers and views this works already, admin still requires a minor code change). Following that pattern, the REST API is auto-generated as well and so should the documentation be.

If it's not clear from the name what the purpose of a field is or how a model is used, it should be documented with the field/model directly and all other elements (GUI, API, etc.) should use that information.

As for general documentation I think the best approach would be to use GirHub's Wiki feature. I will initialize the repo and create a sample page so we have a point to start from.

I just realized I seem to not have written installation instructions yet. I will start writing some.

Regards nomike

BTW: I'm running my instance at https://bautelsortiment.nomike.com where you can have a look.

[achosam]

Hello, please can you provide the base url, so that the endpoints can be tested fro proper descriptions. and does your api require authorization?

**I sent a pull request.

thanks

[Ifedolapo-9]

Hello nomike, Thanks for taking the time to answer my questions

1. The 'bts' (short form for Bauteilsortiment I guess) on the URL works just fine to make it shorter. I think http://bts/api/v0 as a base URL works fine.

2. Yes, I agree that using a "single source of truth" for your API docs is the way to go. Creating a GitHub Wiki also works fine for general documentation.

3. Thanks for stating the locations of the definitions in model.py

Also, to answer your initial question regards how to keep track of new versions of Open API Spec, I suggest creating a separate file dedicated to versioning that can be easily updated. It will contain the current version number. Or You could use Version control tags (Git Tags).

Also, I couldn't access the instance (I guess the instance had stopped running before I could reply). Apologies regarding that. If you don't mind you could let me know when you plan to run the instance so that I can also be around to check it out. Thanks

Best regards, Ifedolapo

[nomike]

Hello there,

I've just found time to have a look at your comments and pull requests.

The only instance of the software I'm currently running (except for the local one on my computer when I'm developing) is hosted on https://bauteilsortiment.nomike.com. There is a URL redirect on https://b.nomi.ke which purely exists to make URLs shorter for the small QR codes I want to slap on the printed labels.

This means that currently there only is a production instance. This should be running 24/7 on my shared hosting provider as a passenger app. It hardly ever sees any requests, so my provider seems to shut down the app after some idle time, which means whenever you do a request, it needs to spawn a new passenger process which executes python which then starts django.

That's why the response time for the first request is quite long sometimes. But other than that, the instance should be reachable all the time. I do not shut it down. And my provider (dreamhost) was always very reliable so far.

I wanted to write installation instructions, so I will just setup a test instance today and document the process while I'm doing it. I could then provide you with usernames and passwords for that instance so you can access the Django backend and have an easier time testing things.

I would also welcome feedback on the installation instructions once I'm done writing them.

Cheers nomike

[nomike]

I've just installed a dev-instance at https://btsdev.nomike.com and added installation instructions to the wiki.

I can create admin users for you on that instance. Let me know please what usernames you want to have and where I can send to password to.

[Ifedolapo-9]

Hello nomike,

Thanks. Great work. Ifedolapo works fine as a username. You can send the password to my mail: ifedolapoojow@gmail.com

I will check out the installation instructions and give my comments.

Thanks, Ifedolapo.

[nomike]

Thanks. Great work. Ifedolapo works fine as a username. You can send the password to my mail: ifedolapoojow@gmail.com

You've got mail!

[Chizobaonorh]

Hello i would love to contribute my skills to your documentation

[Ifedolapo-9]

Helllo nomike, There's a CORS issue that keeps popping up when testing endpoints via swagger editor. Although it doesn't prevent testing, it would be nice if the CORS list was updated in the settings file.