Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Do not use title for objects containing only additionalProperties or patternProperties #1801

Merged
merged 7 commits into from
Apr 30, 2024
Merged

Do not use title for objects containing only additionalProperties or patternProperties #1801

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
07645fc
Do not use title for objects containing only additionalProperties or …
zecakeh Apr 24, 2024
450c147
Add changelog
zecakeh Apr 24, 2024
52da075
Improve docs
zecakeh Apr 24, 2024
7c5e123
Refactor if-else blocks
zecakeh Apr 30, 2024
d33635b
Escape title
zecakeh Apr 30, 2024
7e4977c
Merge branch 'main' into type-not-title-for-additional-pattern
zecakeh Apr 30, 2024
4a1a881
Document properties input for partials
zecakeh Apr 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/internal/newsfragments/1801.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`.
12 changes: 7 additions & 5 deletions layouts/partials/openapi/render-object-table.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,15 +155,17 @@
adhering to a regex pattern

* `anchor`: optional HTML element id for the target type, which will be used to link to it.

The title has a higher priority than anything else.
*/}}
{{ define "partials/object-type-or-title" }}
{{ $type := "object" }}
{{ if .title }}
{{ if and .title (or .properties (not (or .additionalProperties .patternProperties))) }}
zecakeh marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should mention .properties in the comment for this partial.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

{{/*
If the property has a `title`, use that rather than `type`.
This means we can write things like `EventFilter` rather than `object`.
We only want to use the title in two cases:

* The object is rendered as a separate table that will use the same
title, which means that the object must have `properties`.
* The object doesn't define any properties, because showing the title
(like `EventFilter`) is better than showing `object`.
*/}}
{{ $type = .title | htmlEscape }}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I must say this logic makes my head explode, though I think it's probably right.

What if we did something like this instead:

{{ $title = or .title "object" }}
{{ if .anchor }}
    {{ $title = printf "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) $type }}
{{ end }}

{{ if .properties }} 
    {{/*
        The object has its own (regular) properties, so we will make a separate table for it. 
        Refer to it using its title, if it has one.
    */}}
    {{ $type = $title }}
{{ else if reflect.IsMap .additionalProperties }}
    // as before
{{ else if reflect.IsMap .patternProperties }}
    // as before
{{ else }}
    {{/*
        No properties, so there won't be a separate table. We use the title anyway, because showing the title
        (like `EventFilter`) is better than showing `object`.
    */}}
    {{ $type = $title }}
{{ end }}

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's probably easier to read. I'll change it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed

{{ if .anchor }}
Expand Down
Loading