DRAFT export openapi spec generated with utoipa #61
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
benjaminedwardwebb
changed the title
Export an openapi spec for the VTN server with the utoipa crate.
---
This is a draft commit that explores usage of the utoipa crate.
The utoipa crate is popular and well-maintained. It provides macros,
traits, and types for maintaining openapi documentation.
This draft generates documentation for two operations
- GET /vens/{venID}/resources
- POST /vens/{venID}/resources
The document was exported to generated-openapi.yaml with
curl --silent http://localhost:3000/docs/openapi.json | yq --yaml-output . > generated-openapi.yaml
Some callouts
- #[serde(flatten)] is supported, but the generated openapi json schema
uses anyOf to combine the two structs (semantically equivalent but
slightly surprising)
- the effect of other serde attributes and validator constraints may
need to be duplicated as ToSchema macro's schema attributes (not as
bad as it might sound, since these duplicate definitions are placed
essentially next to each other; also there is an issue to consider
adding support for validator's attributes)
- utoipa uses openapi version 3.1.0
Overall, the utoipa crate seems like a popular and safe choice. It
requires a lot of macro boilerplate and there are some details to be
aware relating to serde, but it's very easy to use and gets you 90% of
the way there. And if the macros aren't working, you can always drop
down into traits.
See https://docs.rs/utoipa/latest/utoipa/
and https://crates.io/crates/utoipa
and https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
benjaminedwardwebb
force-pushed
the
benwebb/export-vtn-openapi-specification-utoipa
branch
from
3d9a469 to
004f91a
Compare
|
See discussion in #17 |
benjaminedwardwebb
deleted the
benwebb/export-vtn-openapi-specification-utoipa
branch
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.
Export an openapi spec for the VTN server with the utoipa crate.
This is a draft commit that explores usage of the utoipa crate.
The utoipa crate is popular and well-maintained. It provides macros, traits, and types for maintaining openapi documentation.
This draft generates documentation for two operations
The document was exported to generated-openapi.yaml with
Some callouts
Overall, the utoipa crate seems like a popular and safe choice. It requires a lot of macro boilerplate and there are some details to be aware relating to serde, but it's very easy to use and gets you 90% of the way there. And if the macros aren't working, you can always drop down into traits.
See https://docs.rs/utoipa/latest/utoipa/
and https://crates.io/crates/utoipa
and https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0