Generate API docs

[lucacome]

Proposed changes

Problem: We want to have our CRDs documented

Solution: Use gen-crd-api-reference-docs to automatically generate the
docs

Closes #1754

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.

NONE

[lucacome]

@nginxinc/nginx-docs I need your help to make the new page look good 😅

[ciarams87]

Is there any way to see this page rendered? It doesn't seem to have deployed in Netlify (although I might just be looking in the wrong place 😅)

[lucacome]

seems like it didn't deploy after a force push, we have it now https://deploy-preview-1884--nginx-gateway-fabric.netlify.app/nginx-gateway-fabric/reference/api/

It doesn't look good 😅

[ADubhlaoich]

We should have an example of generated API documentation for other software: I'll inquire with the team what the caveats are.

[travisamartin]

The NGINX One API ref guide just calls the JSON spec and redoc does the formatting auto-magically.

See: https://github.com/nginxinc/docs/blob/main/content/nginx-one/reference/api/nginx-one-api-reference.md

Published output: https://docs.nginx.com/nginx-one/reference/api/nginx-one-api-reference/

[travisamartin]

The doc type is "redoc"

[lucacome]

@travisamartin it's a little bit different from the Open API Spec, we don't have a JSON.
It's something similar to https://gateway-api.sigs.k8s.io/reference/spec/

[lucacome]

@ADubhlaoich @travisamartin any chance you can help with this?

[ADubhlaoich]

@lucacome Some more investigation work is required on our end about if an existing template can be adapted for this.

Does the Gateway API follow a specific, known schema?

[lucacome]

I'm not sure, this is just an html page

[ADubhlaoich]

@Jcahilltorre @travisamartin Any thoughts on the formatting issues for this generated API documentation?

I think there's some examples without these formatting issues in NGINX Management Suite, which are OpenAPI based IIRC.