Openapi plus swagger #514
Openapi plus swagger #514
Conversation
docs/reference/api/api-explorer.md
Outdated
| @@ -0,0 +1,117 @@ | |||
| --- | |||
| title: ApostropheCMS API Documentation | |||
There was a problem hiding this comment.
Just a high level question:
What is the relationship between these pages and our existing REST API documentation?
https://apostrophecms.com/docs/reference/api/README.html#rest-api-route-reference
How should the reader understand when to refer to each? How will each be maintained going forward? Is there redundancy, are there oversights if we eliminate one?
There was a problem hiding this comment.
So, this was more of a landing page that talked about the spec. I think all of our written reference material is valuable and some people will want to just use the OpenAPI spec file and others will want to read long-form. I think we should keep both and keep them up-to-date. The spec file should be kept up because it is the basis for devs generating a customized API for their specific projects. Does that answer your question? Maybe this file should be added as the actual landing page and be redone to address your question about when devs should use each?
There was a problem hiding this comment.
I'm comfortable with having both if both are bringing value. Just make sure they are cross-linked for clarification.
boutell
left a comment
boutell
left a comment
There was a problem hiding this comment.
Rationale makes sense. Please cross-link our handwritten API reference page with this page, in both directions, for clarity.
Summary
Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
This PR adds the API sandbox for the OpenAPI spec file, as well as links to download the OpenAPI file or visit the GitHub repo. This page will be updated once the OpenAPI spec file is also in an outside aggregator like Postman. Note that the dependencies might be different than the existing main, so run
npm updateafter switching to this branch.What are the specific steps to test this change?
For example:
What kind of change does this PR introduce?
(Check at least one)
Make sure the PR fulfills these requirements:
If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.
Other information: