Schema docs #50
Schema docs #50
Conversation
duncanjbrown
force-pushed
the
feature/schema-docs
branch
from
d1c13b4 to
a6fe88b
Compare
|
The frontend looks great, @duncanjbrown. Just one comment on a tiny fix for the sub-headings within "Entities". |
duncanjbrown
force-pushed
the
feature/schema-docs
branch
from
a6fe88b to
0e7329f
Compare
duncanjbrown
force-pushed
the
feature/schema-docs
branch
from
0e7329f to
87f3702
Compare
duncanjbrown
force-pushed
the
feature/schema-docs
branch
from
7130d4f to
8a2b087
Compare
|
|
||
| <p class="govuk-body">This page lists the data components required for a consultation to be suitable for processing by the analyser. </p> | ||
|
|
||
| <p class="govuk-body">Data should be provided in one JSON file containing both the consultation itself and a list of responses. That overall data file is described here and an example is given. Underneath are details of each section, including individual JSON schemas for both the Consultation and ConsultationResponse parts of the JSON file.</p> |
There was a problem hiding this comment.
I wasn't entirely clear on the difference between the 3 schemas and how they are related.
Could make it clear that the ConsultationWithResponses is the one we want e.g. "Data should be provided in one JSON file..... that is valid according to the ConsultationWithResponses schema."
Could be explicit on how the 3 schema relate.
consultation_analyser/consultations/management/commands/generate_json_schemas.py
Outdated
Show resolved
Hide resolved
- Add OpenAPI spec for the schema entities - Use datamodel-codegen to turn the schema into Pydantic models - Use a management command to turn the Pydantic models into JSON schema - Write the lot into public_schema/ - Add Makefile rules (including .PRECIOUS! which turns out to be necessary when you want to hold on to an intermediate file, which we do) to build the schemas and examples from the spec
This allows the template to ask direct questions about the schema object instead of needing to know about how it's implemented
This page documents the schema for file uploads
There was a problem hiding this comment.
These docs and the way they are generated look great - have checked that I can regenerate using make schema_docs.
There are a few minor comments.
I'm going to take liberties and fix the things that need to be fixed (Kev's comment, broken link, incorrect comment), rebase and merge so we can get this in (and so the PR isn't hanging about for ages whilst you're on leave).
There are a few other comments which are suggestions - you might want to look at those later.
nmenezes0
force-pushed
the
feature/schema-docs
branch
from
8a2b087 to
642ea27
Compare
Context
As we request data from participants, we'll need to agree a format for them to submit it.
This PR proposes that format in the standard OpenAPI spec style.
It then takes that information and uses it to generate a documentation page, via some Pydantic models.
It depends on #55, which prepares the
views/directory for these changes.Changes proposed in this pull request
RenderableSchemadecorator and more on the end to end test)Result:
(One JSON open for e.g.)
Guidance to review
Have a click around, look at the OpenAPI YAML spec, look at the Makefile, try making a change to the YAML spec and then re-running
make schema_docs.Link to JIRA ticket
https://technologyprogramme.atlassian.net/jira/software/projects/CON/boards/418?selectedIssue=CON-21
Things to check
.env.exampleand.env.testfiles in the repo