search

block-core / blockcore-vault

Verifiable Credential Server for Web5.
MIT License
12 stars 15 forks source link

Improve API documentation #4

Open sondreb opened 3 years ago

sondreb commented 3 years ago

The OpenAPI (swagger) is generated from the source code comments and can be improved with examples and schemas, making the consuming and learning experience much better.

Leaving this as a good first issue and help wanted, as it requires little pre-existing knowledge of the code base.

ashishgarjetw commented 3 years ago

I'm looking for API technical writing projects. Let me know if you need help.

sondreb commented 3 years ago

I'm looking for API technical writing projects. Let me know if you need help.

Hi and thanks for want to help! You know how to write code, or just technical writing?

The API method is documented like this:

image

And there is a lot of documentation you can add in these sections that the OpenAPI UI supports and will render. You can define schema of data type going in and out of the API, add examples and lots more.

AnujaChangede commented 2 years ago

I'm looking for API technical writing projects. Let me know if you need help.

Hi and thanks for want to help! You know how to write code, or just technical writing?

The API method is documented like this:

image

And there is a lot of documentation you can add in these sections that the OpenAPI UI supports and will render. You can define schema of data type going in and out of the API, add examples and lots more.

Hi! I am a technical writer working in API Documentation. I would like to contribute to the project. I have cloned the repo but do not see anything in the docs folder as yet. Could you please guide me how to get started? Thanks in advance.

sondreb commented 2 years ago

Great to have you here @AnujaChangede! The documentation for this API is put directly on the source code, and you do it within the files located in this folder: https://github.com/block-core/blockcore-vault/tree/main/api/controllers

Example from one of the files:

image

I understand this might be a bit daunting.

We also have made a big update to our main documentation repository where we would also love to get some help.

The repository is here: https://github.com/block-core/documentation

The output is here: https://docs.blockcore.net/

This is only documentation, markdown files, no source code.

AnujaChangede commented 2 years ago

Hi SondreB,

Thanks for answering my query. I have some fundamental questions -

  1. Are you looking for contributions for API Reference (request parameters, response schema, error codes, and so on) documentation?
  2. The files in your controllers folder are all TypeScript files. I am not very well versed with it. I have used Markdown. Do you expect me to read the code and understand it and then write about it?
  3. I have some programming experience. I have worked in C, C++ in the past. Would that be required to write the documentation?
  4. I see that you have recently moved from vuepress to MkDocs. Do you expect me to create content in Markdown files and test it on localhost in Mkdocs before pushing the files?

Looking forward to hearing back from you.

Regards, Anuja

On Fri, Oct 22, 2021 at 2:59 PM SondreB @.***> wrote:

Great to have you here @AnujaChangede https://github.com/AnujaChangede! The documentation for this API is put directly on the source code, and you do it within the files located in this folder: https://github.com/block-core/blockcore-vault/tree/main/api/controllers

Example from one of the files:

[image: image] https://user-images.githubusercontent.com/309938/138430291-1bf39a77-bf53-45d6-9498-cbfbcc92d780.png

I understand this might be a bit daunting.

We also have made a big update to our main documentation repository where we would also love to get some help.

The repository is here: https://github.com/block-core/documentation

The output is here: https://docs.blockcore.net/

This is only documentation, markdown files, no source code.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/block-core/blockcore-vault/issues/4#issuecomment-949450197, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA6PNWFPYK7KQYNIVKLGFL3UIEVHPANCNFSM5CSYHSNQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

-- Wherever you go, no matter what the weather, always carry your own Sunshine!

sondreb commented 2 years ago

Hi again @AnujaChangede, I think the best option would be to have a look at our primary documentation repository and see if there is anything you can contribute on that. It's simply markdown, and it's fairly easy to start the local server (just run doc.bat on Windows) where you get a live preview.

Let me give one example that needs to be updated:

The list of chains here: https://docs.blockcore.net/referencenodes/

Should be the same as here: https://chains.blockcore.net/

I understand it can be a bit daunting to simply start writing documentation for an project you have not coded on or contributed to, so might take some time to get into the functionality, etc.

The Blockcore Vault API is still under development, so you can perhaps wait with additional work on the API documentation until it has stabilized a little more. I'll cleanup the APIs so that the public methods also appears on top of the files.

sondreb commented 2 years ago

@AnujaChangede - Thanks for the pull request! Please join our Discord community if you want to: https://www.blockcore.net/discord

AnujaChangede commented 2 years ago

@AnujaChangede - Thanks for the pull request! Please join our Discord community if you want to: https://www.blockcore.net/discord

thanks @sondreb. Please let me know if theres any other documentation areas I can help into.

Psychodahlia commented 1 year ago

Hi @sondreb I tried to make the changes you suggested. It's my first documentation attempt, so hopefully I didn't mess things up too badly!

Tarlsie commented 1 year ago

Hi do you still need help with API documentation?

sondreb commented 1 year ago

This app is currently a bit on-hold until TBD finishes their Web5 stuff, so keeping this task on-hold for now.

Tarlsie commented 1 year ago

This app is currently a bit on-hold until TBD finishes their Web5 stuff, so keeping this task on-hold for now.

ok, you can message me when you are ready to move forward. And hopefully I will have time to help out then. All the best