Commit Graph

45 Commits (main)

Author SHA1 Message Date
Kévin Commaille 7ec9b7f2e1
Restore heading self links (#2007)
It was a change I did not notice when upgrading Docsy from 0.8.0 to 0.11.0. Docsy changed the way heading self links are generated: they used to be rendered with JS and now they use a Hugo render hook.

This means two things:
- We need to enable them explicitly by overriding the `_default/_markup/render-heading.html` template.
- We need to add the self heading ourselves to headings that are not rendered by Hugo, i.e. HTML headings that we create ourselves.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
6 days ago
Kévin Commaille f3130f70e6
Fix regression introduced when inlining "Required" (#2005)
If the description is not set in the object definition, Hugo generates a weird string after "Required": `%!s(<nil>)`.

To avoid that, we default the description to an empty string when it is not set.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 week ago
Kévin Commaille c16788f991
Remove trailing slash on void HTML elements (#2009)
According to the W3C's HTML validator, trailing slashes in void-element have no effect,
and might interact badly in some cases.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
2 weeks ago
Kévin Commaille d67dd88457
Clean up unused CSS classes in openapi/render-operation partial (#2003)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
2 weeks ago
Kévin Commaille bf8dee74eb
Fix relative URLs when serving the specification with a custom `baseURL` (#1984) 3 weeks ago
Kévin Commaille 1e0919ad12
Rename `custom-formats.yaml` to `string-formats.yaml` (#1977)
It does not contain only custom formats, so the name didn't fit anymore.
Update also the docs to reflect that.
1 month ago
Kévin Commaille 1f5f2c4d83
Enforce consistent vertical spacing between paragraphs in endpoint definitions (#1969)
Use `p` elements to separate paragraphs instead of `br` and enforce single paragraphs to be wrapped in `p` for consistency.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 month ago
Kévin Commaille 18628dc5d7
Allow to specify a prefix for generated HTML IDs of API endpoints (#1882)
* Allow to specify a prefix for generated HTML IDs of API endpoints

Allows to deduplicate IDs of duplicate endpoints

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
6 months ago
Kévin Commaille bd20d946c4
Fix the rendering of the event format for room versions 1 and 2 (#1883)
* Fix rendering of array with items using anyOf

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Use a single definition for Event Hash

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add ending newline

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
6 months ago
Kévin Commaille 094e25b6cd
Ensure more uniqueness for generated HTML IDs (#1881)
* Include method in all API endpoint children's IDs

Avoids duplicate IDs for object of endpoints
that use the same path but a different method.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Differentiate API endpoints' request and response children's IDs

Ensures that the objects have a unique ID compared to other parts of the endpoint.
Mostly useful for the Error type that can be used for responses with different status codes.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Differentiate the names of both SessionData formats

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
6 months ago
Johannes Marbach 27e71fff10
Render added/changed in info on request and response content types (#1876)
* Render added/changed in info on request and response content types

Fixes: #1774
Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
6 months ago
Kévin Commaille 5fbfdd6821
Fix generated HTML (#1880)
* Add tr as child of thead in HTML tables

It is invalid HTML for th to be the direct children of thead

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Remove unnecessary HTML code end tag

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Avoid nesting p HTML elements

A p HTML element cannot contain other block elements,
so the "parent" element is closed when the first "child" one is opened.

We need to use Page.RenderString with options
to force Hugo to keep the wrapping p elements
even if the content contains a single paragraph.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add missing HTML details end tags

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Replace HTML a self-closing tag with start and end tags

The a element start and end tags are mandatory.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Replace obsolete HTML name attribute with id

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
6 months ago
Kévin Commaille 98d85cf421
Add support for rendering string formats (#1814)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
7 months ago
Richard van der Hoff 48f4c4954f
Include information about additionalProperties in object tables (#1798)
Currently, if we have an object which has additionalProperties in addition to properties, that information gets lost. This PR seeks to address that.
7 months ago
Kévin Commaille 1fc25d8d48
Do not use `title` for objects containing only `additionalProperties` or `patternProperties` (#1801)
Previously, titles would appear that do not link to a subchema definition.
It would also mean that named subschemas would appear without being clearly referenced.

Now, the type clearly shows the nesting of objects
and subschema definitions should be clearly referenced.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
7 months ago
Kévin Commaille 85ad0c767c
Render response headers (#1809)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
7 months ago
Kévin Commaille 2edfb21d5d
Add support for pattern formats for `patternProperties` (#1796)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
7 months ago
Kévin Commaille 1095179374
Upgrade version of Hugo used to build the spec in CI (#1794)
* Upgrade version of Hugo used to build the spec in CI

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Escape HTML manually in property-type partial

The behavior of `delimit` changed,
so Hugo doesn't recognize "safe" HTML passed to it anymore, so it escapes nested HTML links.

To fix that we escape the schema data manually
and consider the output of the partial as "safe".

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
8 months ago
Kévin Commaille e82829d4a2
Make resolve-allof partial recursive (#1787)
Makes it easier to use, like resolve-refs. It just needs to be called once.

Fixes an issue with m.call.* events not displaying the common fields

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
8 months ago
Kévin Commaille f4e7b2aa97
Fix property type resolution in render-object-table (#1789)
The split was not clear between property-type and type-or-title,
so it was not obvious which partial should be called for recursion.
That resulted in an error where type-or-title was only called for objects and array items, even if it also resolves
arrays of types.

This makes the split clearer. property-type must be called for any schema,
and object-type-or-title is only called for object schemas.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
8 months ago
Kévin Commaille 2678370f2c
Simplify uses of `resolve-refs` partial (#1773)
* Use the resolve-refs partial as soon as possible

Call it right after accessing the site.Data,
since it is recursing it will solve all references in the tree.
That way we don't need to wonder where to call it,
we trust the validators that the refs will be used in the right place.

* Enable strict $ref rule in OpenAPI validator

* Document use of $ref to compose examples

* Fix schema path in event-fields shortcode

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
8 months ago
Travis Ralston eb22fac5dc
Break out non-JSON request/response content types as tables (#1756)
* Break out non-JSON request/response content types as tables

Currently we display this as a table like "image/png|image/jpeg" and description on a single line, but we're using a table. This breaks the join out to individual rows.

* changelog
9 months ago
Kévin Commaille 4d7e33ec26
Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas (#1751)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
9 months ago
Kévin Commaille 542a219623
Allow `/versions` to optionally accept authentication (#1728)
* Allow /versions to optionally accept authentication

According to MSC2046.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Set "Requires Authentication: Optional"

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
9 months ago
Richard van der Hoff 976ebdca2f
Update HTML templates to link to object definitions (#1724) 9 months ago
Kévin Commaille e40d9ca186
Fix rendering of `m.receipt` event in Client-Server API (#1637)
... and other improvements

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
1 year ago
Kévin Commaille 5672bdbab7
Fix enum types in JSON schemas (#1634)
`type: enum` does not exist, as an enum can be of any type.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 year ago
Kévin Commaille 99e2ff4927
Replace all mentions of Swagger by OpenAPI (#1633)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 year ago
Kévin Commaille 50fe89d74b
Fix definition of response of `POST /_matrix/federation/v1/user/keys/claim` (#1559)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 year ago
Kévin Commaille 564444d43e
Render binary request and response bodies (#1579)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
1 year ago
Kévin Commaille 49957be1e3
Allow `null` in `room_types` for `POST /publicRooms` endpoints (#1564)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
2 years ago
Kévin Commaille 45b6aaf07a
Upgrade Swagger data to OpenAPI 3.1 (#1310)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
2 years ago
Richard van der Hoff cdbf44eef0
Fix rendering of properties with a list of types (#1487) 2 years ago
David Robertson f9ea0f9d9b
Only include endpoint path in `<summary>` (#1446) 2 years ago
Patrick Cloke 1c0101ce4c Put commas between enum values. 2 years ago
David Robertson a6990ff27c
Fix spacing of mapping types (#1230)
* Fix spacing of mapping types

* Changelog
2 years ago
Richard van der Hoff ef384f1afd
Give rendered-data sections a background and some padding (#1195)
Gives definition sections for APIs, events, etc a background and a small indent, which I find very helpful to guide the eye.
2 years ago
Richard van der Hoff 5f3b34448d
Add HTML ids for object definitions in the formatted specification (#1174)
* Remove redundant call to resolve-allof

All of the callers to resolve-additional-types already call resolve-allof (or
if not, they should), so this is redundant.

* Update `resolve-additional-types` to take a dict

I want to add more params to this, so first make it take a dict.

* `render-object-table`: take a "title" rather than a "caption"

... which means we can use the result from resolve-additional-types directly.

* render-object-table: support adding an anchor to generated tables.

* resolve-additional-types: generate an id for each returned type

* render-event: pass an anchor_base into resolve-additional-types

This means that it will generate an anchor for each type, whihc will then be
passed into render-object-table and used as an `id` for the table.

* render-operation: pass an anchor_base into resolve-additional-types

* newsfiles
2 years ago
Richard van der Hoff dfb1bf2a5d
Fix `x-changedInMatrixVersion` for API parameters (#1011) 3 years ago
Richard van der Hoff 783624d2cd
Fix rendering of responses with empty bodies (#3674) 3 years ago
Richard van der Hoff 3be746c9d3
Fix rendering of response examples (#3584)
* Fix rendering of response examples

Fixes the autogeneration of JSON examples for array objects. This fixes a
number of "Specification error: Example invalid or not present" errors in the
rendered spec.

* Unbreak examples for non-objects/arrays

The previous change had broken auto-generated examples for everything that
wasn't an object or array; fix it up again.

* Remove conditions on $example

Everything should now have a generated example, so the condition is
redundant. Furthermore it was suppressing examples for APIs where the example
was an empty dict.
3 years ago
Richard van der Hoff 7f200c53e8
Move `prev_content` to unsigned (#3524) 3 years ago
Travis Ralston 5be0df02c5
Start annotating which version of the spec added a thing (#3425)
* Introduce a new "added-in" template and use it on endpoints

* Use "added-in" on schema properties too

* Annotate sections of the spec with their added versions

* Demo of "added-in" on a room version (to be fleshed out)

* Use clearer versioning semantics

* Update and fix validator for Swagger custom properties

* Fix docs
3 years ago
wbamberg 6fc1f52f2f Fix typo in comment
Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
3 years ago
Will 5f45a897ef Add templates used to render data 3 years ago