mirror of
https://github.com/openfoodfoundation/openfoodnetwork
synced 2026-01-24 20:36:49 +00:00
db77d1591c
In other API specs, you provide example values in the schema. So the specs contain examples which can be used for the documentation. But instead of defining example data separately, we can use the generated data by the specs. This way we document real output and don't have to double up on documentation. Note that we don't have schema definitions for the DFC API yet. And it wouldn't make sense to replicate the DFC Ontology manually in JSON Schema for this purpose. The DFC Connector ensures already that we comply with the ontology. But I hope that we can use a tool at some point to generate JSON Schema from the DFC Ontology which would add more detail to the Swagger docs, I think.
18 lines
747 B
Bash
Executable File
18 lines
747 B
Bash
Executable File
#!/usr/bin/env sh
|
|
|
|
# Generate the API documentation based on our specs.
|
|
#
|
|
# The standard way to generate the documentation is `rake rswag` which calls
|
|
# rspec under the hood. We have a few customisations to the rspec call though
|
|
# which only work when calling rspec ourselves.
|
|
#
|
|
# - We actually run the specs to generate examples instead of a dry run.
|
|
# While rswag has an RSWAG_DRY_RUN switch, it doesn't work with our setup.
|
|
# - We add relevant engines to the pattern.
|
|
# - We run only tagged swagger specs instead of all matching the pattern.
|
|
exec ./bin/rspec\
|
|
--pattern "spec/requests/api/**/*_spec.rb,engines/dfc_provider/spec/requests/**/*_spec.rb"\
|
|
--tag "swagger_doc"\
|
|
--format "Rswag::Specs::SwaggerFormatter"\
|
|
--order "defined"
|