diff --git a/packages/ccdi-openapi/src/api.rs b/packages/ccdi-openapi/src/api.rs index 9724289..d5143c5 100644 --- a/packages/ccdi-openapi/src/api.rs +++ b/packages/ccdi-openapi/src/api.rs @@ -88,6 +88,9 @@ a variety of query parameters.", // Models. models::Subject, + models::metadata::field::Description, + models::metadata::field::description::Harmonized, + models::metadata::field::description::Unharmonized, models::subject::Kind, models::subject::Metadata, @@ -98,6 +101,8 @@ a variety of query parameters.", responses::Error, responses::Subject, responses::Subjects, + responses::by::count::Subjects, + responses::metadata::FieldDescriptions )), modifiers(&RemoveLicense) )] diff --git a/packages/ccdi-server/src/responses/by/count.rs b/packages/ccdi-server/src/responses/by/count.rs index 00dc083..2a277e7 100644 --- a/packages/ccdi-server/src/responses/by/count.rs +++ b/packages/ccdi-server/src/responses/by/count.rs @@ -7,14 +7,13 @@ use utoipa::ToSchema; use ccdi_models as models; -use models::count::Total; - /// A response for grouping [`Subject`](models::Subject)s by a metadata field /// and then summing the counts. #[derive(Debug, Deserialize, Serialize, ToSchema)] +#[schema(as = responses::by::count::Subjects)] pub struct Subjects { #[serde(flatten)] - total: Total, + total: models::count::Total, values: IndexMap, } @@ -44,7 +43,7 @@ impl From> for Subjects { fn from(values: IndexMap) -> Self { let total = values.values().sum::(); Self { - total: Total::from(total), + total: models::count::Total::from(total), values, } } diff --git a/packages/ccdi-server/src/routes/metadata.rs b/packages/ccdi-server/src/routes/metadata.rs index 4af7102..58da080 100644 --- a/packages/ccdi-server/src/routes/metadata.rs +++ b/packages/ccdi-server/src/routes/metadata.rs @@ -25,7 +25,7 @@ pub fn configure() -> impl FnOnce(&mut ServiceConfig) { path = "/metadata/fields/subject", tag = "Metadata", responses( - (status = 200, description = "Successful operation.", body = [responses::Subjects]) + (status = 200, description = "Successful operation.", body = responses::metadata::FieldDescriptions) ) )] #[get("/metadata/fields/subject")] diff --git a/packages/ccdi-server/src/routes/subject.rs b/packages/ccdi-server/src/routes/subject.rs index 823502c..507a5ae 100644 --- a/packages/ccdi-server/src/routes/subject.rs +++ b/packages/ccdi-server/src/routes/subject.rs @@ -137,7 +137,7 @@ pub async fn show(path: Path<(String, String)>, subjects: Data) -> impl R ), tag = "Subject", responses( - (status = 200, description = "Successful operation.", body = responses::Subject), + (status = 200, description = "Successful operation.", body = responses::by::count::Subjects), ( status = 422, description = "Unsupported field.", diff --git a/swagger.yml b/swagger.yml index fa6c7f1..d7d687e 100644 --- a/swagger.yml +++ b/swagger.yml @@ -32,9 +32,7 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/responses.Subjects' + $ref: '#/components/schemas/responses.metadata.FieldDescriptions' /subject: get: tags: @@ -104,7 +102,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/responses.Subject' + $ref: '#/components/schemas/responses.by.count.Subjects' '422': description: Unsupported field. content: @@ -363,6 +361,86 @@ components: type: integer description: The total number of entities returned in the API call. minimum: 0 + models.metadata.field.Description: + oneOf: + - $ref: '#/components/schemas/models.metadata.field.description.Harmonized' + - $ref: '#/components/schemas/models.metadata.field.description.Unharmonized' + description: A description for a metadata field. + models.metadata.field.description.Harmonized: + type: object + description: A harmonized metadata field description. + required: + - harmonized + - path + - standard + - url + properties: + harmonized: + type: boolean + description: |- + Whether or not this field is harmonized across the ecosystem. + + This will always be set to `true`. + default: true + path: + type: string + description: |- + A comma (`.`) delimited path to the field's location on the `metadata` + objects returned by the various subject endpoints. + standard: + type: string + description: |- + The proper name of the standard to which this field is harmonized (defined + by the documentation for the CCDI metadata fields). + url: + type: string + description: |- + A URL to the CCDI documentation where the definition of this harmonized + field resides. + models.metadata.field.description.Unharmonized: + type: object + description: An unharmonized metadata field description. + required: + - harmonized + - path + properties: + harmonized: + type: boolean + description: |- + Whether or not this field is harmonized across the ecosystem. + + This will always be set to `false`. + default: false + name: + type: string + description: |- + A display name for this metadata field as _suggested_ by the server (this + is not considered authoritative and can be ignored by the client if it so + chooses). This is mainly to avoid naming collisions of common fields across + servers. + nullable: true + description: + type: string + description: A plain-text description of what the field represents. + nullable: true + path: + type: string + description: |- + A comma (`.`) delimited path to the field's location on the `metadata` + objects returned by the various subject endpoints. + standard: + type: string + description: |- + If the field is considered harmonized across the federation ecosystem, the + name of the standard to which the field is harmonized. + + If the field is _not_ harmonized across the federation ecosystem, then this + should be [`None`]. + nullable: true + url: + type: string + description: A url that describes more about the metadata field, if available. + nullable: true models.subject.Kind: type: string description: A kind of [`Subject`](super::Subject). @@ -435,6 +513,32 @@ components: items: $ref: '#/components/schemas/models.Subject' description: The subjects, if available. + responses.by.count.Subjects: + allOf: + - $ref: '#/components/schemas/models.count.Total' + - type: object + required: + - values + properties: + values: + type: object + additionalProperties: + type: integer + minimum: 0 + description: |- + A response for grouping [`Subject`](models::Subject)s by a metadata field + and then summing the counts. + responses.metadata.FieldDescriptions: + type: object + description: A response for describing metadata fields for a subject. + required: + - fields + properties: + fields: + type: array + items: + $ref: '#/components/schemas/models.metadata.field.Description' + description: Field descriptions. tags: - name: Info description: Information about the API implementation itself.