Developer Docs [FEATURE]

[cgsmith]

Is your feature request related to a problem? Please describe. Currently we have the Swagger docs but these are fairly technical. I'd like to discuss how to build a guide like shown on Yii2 website. This would be a developer doc that would also include Swagger docs for more details. I've looked at things like ReadMe.com or Gitbook.com and those look like nice solutions.

Opening this up for discussion. @cebe I'd like to know your opinion on building some developer friendly docs for Shipwise.

[cgsmith]

Leaning toward Gitbook. Also have application docs that will be on support.getshipwise.com/Freshdesk

[samdark]

Usually developer docs are written, not generated. Swagger can't replace writing.

So markdown writing is needed with clear concepts explanation, use-cases, examples and links to swagger docs. How to render these docs is not that hard question. We can use Yii2's apidoc for that or come up with a simple custom rendering or use GitHub pages linked to a sub-domain.

[samdark]

So:

1. Stabilize API.
2. Version it.
3. Get everything documented via OpenAPI annotations.
4. Have swagger API UI.
5. Write guide in markdown.
6. Render it somehow.

[bohdan-vorona]

If replace Swagger with something else, I've found:

1. Docsify. URL: https://docsify.js.org/#/

A lightweight. It parses markdown files and displays them as a website. Examples - https://github.com/docsifyjs/awesome-docsify#showcase

But, as Alexander wrote, we will need to write documentation manually using markdown language.

2. Docusaurus. URL: https://docusaurus.io/docs

Examples - https://docusaurus.io/showcase?tags=favorite

3. If continue using OpenAPI/Swagger, Redoc. URL: https://github.com/Redocly/redoc

Examples - https://redocly.github.io/redoc/

4. API Blueprint. URLs: https://apiblueprint.org/, https://github.com/apiaryio/api-blueprint

5. Read the Docs. URL: https://readthedocs.org/

Example - https://dredd.org/en/latest/

[cgsmith]

Ok - Going to keep this issue open for now. I am ok with still using Swagger but need to have it be validated at build time (I'll create a separate issue for this).

Leaning towards Gitbook or ReadTheDocs that builds with a github repo.

[cebe]

Guide-like developer documentation should be additional to Swagger/OpenAPI docs. There are two different use cases:

1. devs read the guide to get into the concepts behind the platform and to understand the overall idea of how integration will work
2. devs read the swagger docs for specific information about an API endpoint.

Both should exist and link to each other. Alternatively we can integrate the Guide description directly in the Swagger docs, not sure how it will display in the swagger UI we have now, but I have done this with Redoc:

https://wawi.king4pets.com/v1/docs/#tag/Articles

About tooling:

As we already have the swagger stack installed I'd keep it. Compared to other tools it provides the option to try the API directly from within the documentation. Redoc for example does not have this.

Validation of swagger docs at build time is useful if we write the Swagger/OpenAPI yaml or json ourselfs. As these are generated from PHPDoc annotations right now, I don't see a good reason to validate something there.

yii2-apidoc could also be used to render documentation from markdown files inside the repository.

[cgsmith]

Just met with Shea at Readme.com - free version will work and we can use paid version when needed