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.

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

Add pages for OAD examples #105

Merged
merged 15 commits into from
Aug 21, 2024
Merged

Add pages for OAD examples #105

merged 15 commits into from
Aug 21, 2024

Conversation

ralfhandl
Copy link
Contributor

@ralfhandl ralfhandl commented Aug 14, 2024

Part of OAI/OpenAPI-Specification#3854

Each example to be shown on the site needs a small markdown file which pulls in the JSON and YAML files via an include:

---
layout: default
title: api-with-examples
parent: Example API Descriptions
---

{% comment %}
{% capture description %}
Insert description here, then remove comment tag above and endcomment tag below
{% endcapture %}
{% endcomment %}

{% include example-api-description.md name=page.title description=description %}

The title in the front matter determines which sibling JSON and YAML files are embedded in code blocks, the name of the markdown file itself is irrelevant, although it is nice to use the same basename as for the JSON and YAML files.

See rendering on https://ralfhandl.github.io/learn.openapis.org/examples/v3.1/non-oauth-scopes.html

because the highlighted ones false positives (bug in kramdown/rouge? don't want to invest time), and we test the YAML files against the JSON Schema for OpenAPI, so they are more than just syntactically correct
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Don't yamlize examples

Copy link
Member

@handrews handrews left a comment

Choose a reason for hiding this comment

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

I'm assuming all the noise in the json/yaml files is auto-reformatting and didn't review it in detail (looks fine based on a skim).

I did check the markdown, page titles, and other files, and they all look good.

and adjust workflow to use same formatter
@miqui
Copy link
Collaborator

miqui commented Aug 21, 2024

checked the md, looks good to me.

@miqui miqui merged commit 87c005c into OAI:main Aug 21, 2024
1 check passed
@ralfhandl ralfhandl deleted the add-examples branch August 22, 2024 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Move examples to learn.openapis.org or spec.openapis.org
4 participants