[RFC] Document CF API V3 with OpenAPI #1256
Conversation
FloThinksPi
changed the title
|
|
||
| ### Phases | ||
|
|
||
| **Implementation** - Convert <https://github.com/cloudfoundry-community/capi-openapi-spec> to a repository in the official cloudfoundry organization.Document the CF API V3 using the OpenAPI specification. Also generate a html documentation to replace the current page. Optionally build up, if possible, a validation(integration test) that validates if the OpenAPI spec is in sync with the actual implementation of the CF API V3. |
There was a problem hiding this comment.
thought I see this is using perl code to generate the API. There isn't much (any?) perl in the CF OSS so I'd be concerned about the maintainability of continuing this approach.
There was a problem hiding this comment.
Indeed something to replace, but thats gonna be easy to overhaul when the PoC is in a official CF repo. We will try out different tooling and adopt that. Ultimately figuring out everything before it goes to the CC_NG repo.
There was a problem hiding this comment.
I would start with a POC phase that demonstrates different options how to convert the existing implementation into an OpenAPI spec including how CAPI devs would update it. One non-trivial endpoint should be enough but this endpoint should be implemented completely.
Whether we use the mentioned approach from the community project or not is a detail.
| - [AI Agents](https://github.com/janwilmake/openapi-mcp-server) for improved integration with AI-powered tools. | ||
|
|
||
| ### Phases | ||
|
|
There was a problem hiding this comment.
thought Should the spec/generation eventually just live in the https://github.com/cloudfoundry/cloud_controller_ng repository?
There was a problem hiding this comment.
Yep definitely, the idea is to work on it in a separate repo until we want to switch the leading documentation format - then we copy it over into the CC_NG repo, including the processes(release webpage etc.) which likely will be based on GitHub actions - and archive the one.
| - [AI Agents](https://github.com/janwilmake/openapi-mcp-server) for improved integration with AI-powered tools. | ||
|
|
||
| ### Phases | ||
|
|
There was a problem hiding this comment.
thought https://github.com/rswag/rswag would be an interesting approach, create request specs that can be used to generate open api spec. That way we get a open api doc and some verification in a single definition. However that would mean creating/updating whole bunch of requests specs.
There was a problem hiding this comment.
I tried that before the issue with that is that we dont use native rails - e.g. we dont use active records but sequel library for the models. Rswag just worked for me when its a absolute default ruby project. But i also like to give it a shot again since i last tried it 1-2 years ago. Optimally we could use something like that but in any case writing the OpenAPI spec by hand is already an improvement from writing the HTML/MD page oneself i guess. Especially for the consumer side the format is the only thing that matters. How its produced is secondary for a CF consumer, relevant for the Working Group though.
|
From a Broadcom side we're interested in helping with this effort and maintaining an OpenAPI spec for CAPI. |
There was a problem hiding this comment.
Another point to think about: how to continue with the existing CF client libs: cf-java-client and go-cfclient?
Do we maintain multiple client libs? The existing ones for compatibility and the potentially new ones that are (partly) generated from the OpenAPI spec.
The existing ones provide additional value on top of the pure language bindings:
- authentication support and token refresh
- pagination handling
- slicing long guid lists into chunks that fit into urls
- higher level operations (cf-java-client has an operations api but only for v2)
- integration of additional api endpoints like loggregator
This goes probably beyond this RFC. The spec clearly helps to get a language binding for the CF API from scratch which is good if no library exists yet or is hopelessly outdated. But if usable client libs exist (java, golang, also python), it becomes a longer way.
| **Implementation** - Convert <https://github.com/cloudfoundry-community/capi-openapi-spec> to a repository in the official cloudfoundry organization.Document the CF API V3 using the OpenAPI specification. Also generate a html documentation to replace the current page. Optionally build up, if possible, a validation(integration test) that validates if the OpenAPI spec is in sync with the actual implementation of the CF API V3. | ||
|
|
||
| **Checkpoint** - TOC review and approval of the project, ensuring the | ||
| OpenAPI documentation is complete in comparison to the current one and of appropriate quality. Replacement of the current CF API V3 website with representing the OpenAPI spec. Also release the OpenAPI spec for programmatic access to the CF API V3 documentation. |
There was a problem hiding this comment.
Not sure if this needs TOC approval, ARI WG approval should be enough.
There was a problem hiding this comment.
First checkpoint is probably the POC (one endpoint):
- How to create the initial spec from existing API documentation? (the mentioned POC shows one way)
- Does the dev process work?
- How is it integrated into CI and CAPI release process?
- Can we test the spec against the implementation?
- Maybe there is a way to generate the spec from source code. How would this look like? Where can we maintain metadata like examples, manually written docs etc in the sources?
Next phases could then be:
- complete implementation
- checkpoint as mentioned
- Is the spec complete and usable?
- remove old API documentation
|
|
||
| ### Phases | ||
|
|
||
| **Implementation** - Convert <https://github.com/cloudfoundry-community/capi-openapi-spec> to a repository in the official cloudfoundry organization.Document the CF API V3 using the OpenAPI specification. Also generate a html documentation to replace the current page. Optionally build up, if possible, a validation(integration test) that validates if the OpenAPI spec is in sync with the actual implementation of the CF API V3. |
There was a problem hiding this comment.
I would start with a POC phase that demonstrates different options how to convert the existing implementation into an OpenAPI spec including how CAPI devs would update it. One non-trivial endpoint should be enough but this endpoint should be implemented completely.
Whether we use the mentioned approach from the community project or not is a detail.
Request repository to work on #1256
There was a problem hiding this comment.
I would suggest following improvements in the RFC:
- The RFC should explicitly state that the ARI WG will be impacted by this initiative and will need to invest into this effort.
- The checkpoint phase should additionally define that the OpenAPI effort should be stopped if the expected spec quality can't be implemented.
- It could include a Future Improvements section that outlines potential benefits beyond initial implementation like SDK generation which could be adopted by existing CF clients and make clear that this is out of scope for this RFC.
Yea i considerd this in the draft for the RFC but removed it since it bloats it up quite a lot. I think its good to keep that in mind as follow up of this RFC. |
FloThinksPi
force-pushed
the
rfc-openapi
branch
from
3222441 to
b337168
Compare
|
I made some adoptions and worked in @beyhan and @stephanme comments. |
Just as a side note this was already briefly discussed in the App Runtime Interfaces WG and had positive feedback that something like that is thinkable for the WG
Link for easy viewing