feat: Add OpenAPI documentation for API endpoints

[DeleMike]

Contributor checklist

• This pull request is on a separate branch and not the main branch
• I have ran the ./pre-commit executable as well as make lint and have fixed all reported issues

---

Description

Adds OpenAPI documentation to Scribe-Server, making it easier for developers to understand and integrate with our language data API.

How to test

• Install the Swagger CLI tool (one-time setup):

go install github.com/swaggo/swag/cmd/swag@latest

• Generate docs and run the server:

make docs    # Generate OpenAPI documentation
make dev     # Start development server

Related issue

• closes Setup user-facing documentation for the API #9

[ghost]

Thank you for the pull request! ❤️

The Scribe-Server team will do our best to address your contribution as soon as we can. If you're not already a member of our public Matrix community, please consider joining! We'd suggest that you use the Element client as well as Element X for a mobile app, and definitely join the General and Data rooms once you're in. Also consider attending our bi-weekly Saturday dev syncs. It'd be great to meet you 😊

[ghost]

Maintainer Checklist

The following is a checklist for maintainers to make sure this process goes as well as possible. Feel free to address the points below yourself in further commits if you realize that actions are needed :)

• The CHANGELOG has been updated with a description of the changes for the upcoming release and the corresponding issue (if necessary)
• The continuous integration (CI) workflows within the PR checks do not indicate new errors in the files changed

[andrewtavis]

Hey @DeleMike 👋 I did the commands listed to make the docs and it's not working 🤔 Commands are:

>> make docs
Generating API documentation...
swag is not installed. Please run 'make install-tools' first.
make: *** [docs] Error 1
>> go install github.com/swaggo/swag/cmd/swag@latest
# Succeeds
>> make docs
Generating API documentation...
swag is not installed. Please run 'make install-tools' first.
make: *** [docs] Error 1
>> make install-tools
# Succeeds
>> make docs
Generating API documentation...
swag is not installed. Please run 'make install-tools' first.
make: *** [docs] Error 1

Note that there are some commits above that edit the markdown files to add in directions for generating the docs. Let's remember to update those with the necessary steps!

[DeleMike]

Thanks for the review @andrewtavis!

This is strange. I will check it out, and I will update the docs if necessary.

[DeleMike]

Hi @andrewtavis and @axif0 can you please test this if it works. It is hard for me to reproduce the bug, so I tried to make it work by ensuring that we use the SYSTEM Go's path instead of making it relative.

Looking forward to your reviews!

[axif0]

Now I can make and run the routes -

http://localhost:8080/swagger/index.html

A question is that don't we also need to remove unnecessary library like sqlc library from installing? @DeleMike ~

[DeleMike]

Thanks for the feedback 🚀🔥

Okay, I will remove unnecessary libraries. Thanks for pointing me towards that!

[andrewtavis]

Thanks, @axif0 and @DeleMike! Let's also add http://localhost:8080/swagger/index.html to the docs so the user knows where to find them :)

[DeleMike]

Thanks, @axif0 and @DeleMike! Let's also add http://localhost:8080/swagger/index.html to the docs so the user knows where to find them :)

Sure! Thanks 😊

[DeleMike]

Hi @andrewtavis and @axif0, I've updated the PR.
I improved the docs and also removed unnecessary libraries

[andrewtavis]

All's working great, @DeleMike! So amazing that the service is getting to a point where it's so well rounded! Really is getting there for an initial release 😊

[DeleMike]

Thank you so much! Can't wait for the official release! ✨🚀