OpenAPI Spec, try 2 #2803
Merged
OpenAPI Spec, try 2 #2803
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Great start, thanks! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is another attempt to do the OpenAPI spec better than initially done in #2671. That PR focused on the Collections endpoints, but this PR focuses on a stripped down version of the Author endpoints to make reviewing easier (the missing schemas will be added back in future PRs).
I changed from OpenAPI 3.1 to OpenAPI 3.0 due to better tool support as of March 2024. I still prefer 3.1, but migrating will be easier than writing it all from scratch twice.
I opted to create a new directory named
docs/for the API spec files which matches the source code structure. Whileswagger-jsdocdid work well, it makes editing the schemas more difficult because VSCode cannot assist with any formatting in the block comments. Separating the documentation and code into their own files but keeping it in the same repository should still help keep the API docs up to date as unit/integration testing is added.Initial research shows other projects tend to keep their OpenAPI spec in the same repository as the source code.
I am using the
vacuumtool for bundling and linting the spec. Running the tool is discussed indocs/README.md.