Skip to content

gh-pages: Generalize registry site to publications #4226

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

Merged
merged 3 commits into from
Nov 28, 2024
Merged

gh-pages: Generalize registry site to publications #4226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7cabdd7
Generalize registry site to publications
handrews Nov 26, 2024
947559d
Shrink latest spec button text
handrews Nov 26, 2024
20893ba
Further guidance on schemas.
handrews Nov 26, 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
10 changes: 6 additions & 4 deletions _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# theme: just-the-docs
remote_theme: just-the-docs/just-the-docs
color_scheme: oai
title: OpenAPI Initiative Registry
description: Extensible data value repository
title: OpenAPI Initiative Publications
description: Specifications, registries, and schemas
show_downloads: true
excerpt_separator: ""
collections_dir: /registries
Expand Down Expand Up @@ -59,10 +59,12 @@ plugins:
- jekyll-remote-theme
- jekyll-sitemap
aux_links:
"Latest OpenAPI Specification":
"Latest OpenAPI Spec":
- "https://spec.openapis.org/oas/latest.html"
"Latest Arazzo Specification":
"Latest Arazzo Spec":
- "https://spec.openapis.org/arazzo/latest.html"
"Latest Overlay Spec":
- "https://spec.openapis.org/overlay/latest.html"
Copy link
Contributor

Choose a reason for hiding this comment

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

This pushes the search field narrower and cuts off "Search OpenAPI Initia"
Screenshot 2024-11-26 at 12 29 11

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah, Jekyll and Liquid are horrible and have very few layout options. Maybe change "Specification" to "Spec" and change "Search OpenAPI Initiative Registry" to just "Search". because it does search the whole spec site AFAICT.

Copy link
Member Author

Choose a reason for hiding this comment

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

@notEthan I truncated "specification" to "spec". It turns out Jekyll/Liquid put whatever the site's title is in the Search box and I have no idea how to turn it off or change it, and I'm way past my Jekyll/Liquid frustration level at this point as they are the absolute worst I've been forced to work with and fill me with rage every time I attempt any improvement. So someone else can deal with that.

Copy link

Choose a reason for hiding this comment

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

What I need to do let me know please thank you

footer_content: "\xA9 2024 OpenAPI Initiative.
<br />This work is licensed under the <a rel=\"license\" href=\"https://www.apache.org/licenses/LICENSE-2.0\"\
>Apache 2.0 License</a>. This site is\
Expand Down
48 changes: 33 additions & 15 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,47 @@ description: HTML Spec. and extensible registry
layout: default
---

# OpenAPI Initiative Registry
# OpenAPI Initiative Publications

This site contains the OpenAPI Initiative Registry and content for the HTML versions of specifications managed by the OpenAPI Initiative such as the OpenAPI Specification and the Arazzo Specification.
This site contains the authoritative HTML renderings of the OpenAPI Initiative's [specifications](#specifications) and [extension registries](#registries), as well as official (but non-[normative](https://en.wikipedia.org/wiki/Normativity#Standards_documents)) [schemas](#non-normative-json-schemas) for those specifications that provide them.

## Registry
Please see the [Learn OpenAPI](https://learn.openapis.org) site for additional documentation and [examples](https://learn.openapis.org/examples/), and the [OpenAPI Tooling](https://tools.openapis.org/) site for community-provided lists of tools implementing the specifications.

* Proceed to [Registry](./registry/index.html)
## Specifications

## Arazzo Specification

### Versions
### Arazzo Specification

{% include specification-version-list.md specification="arazzo" %}

## OpenAPI Specification

### Versions
### OpenAPI Specification

{% include specification-version-list.md specification="oas" %}

### Non-Normative JSON Schemas
### Overlay Specification

{% include specification-version-list.md specification="overlay" %}

## Registries

The [Registry Page](./registry/index.html) includes documentation as well as API and RSS access for all registries

Registry shortcuts:
{% for registry in site.collections %}{% unless registry.hidden %}
* <a href="registry/{{ registry.slug }}">{{ registry.name }}</a>{% endunless %}{% endfor %}

## Non-Normative JSON Schemas

_Note that while schemas can catch many errors, they are not guaranteed to catch all specification violations. In the event of a disagreement between the schemas and the corresponding specificaton text, the specification text is presumed to be correct._

### Arazzo Schemas

_TBD_

### OpenAPI Specification Schemas

Note that the OAS 3.1 `schema/YYYY-MM-DD` schema does _not_ validate the Schema Object, as it makes no assumptions about the JSON Schema dialect in use. The OAS 3.1 `schema-base/YYYY-MM-DD` schema _does_ validate the Schema Object, and requires that if `jsonSchemaDialect` or `$schema` are present, that they use the appropriate `dialect/YYYY-MM-DD`. The name `schema-base` comes from the JSON Schema dialect including the OAS extensions being referred to as the "base dialect" in the specification.

See [issue #4147](https://github.com/OAI/OpenAPI-Specification/issues/4147) for discussion of other possible JSON Schema dialect options, [issue #4152](https://github.com/OAI/OpenAPI-Specification/issues/4152) for programmatic access to the latest schemas, and [issue #4141](https://github.com/OAI/OpenAPI-Specification/issues/4141) for discussions on possibly providing linting schemas that could catch likely problems that do not directly violate the specification.

{% assign schema_files = site.static_files | where: "extname", "" | sort: "path" | reverse %}
{% assign last_version = "" %}
Expand All @@ -50,8 +70,6 @@ This site contains the OpenAPI Initiative Registry and content for the HTML vers
{%- endif -%}
{%- endfor %}

## Overlay Specification
### Overlay Specification Schemas

### Versions

{% include specification-version-list.md specification="overlay" %}
_TBD_