oai / learn.openapis.org Goto Github PK

On several pages, the link to the Toc-Tac-Toe example does not work correctly, e. g.

• https://oai.github.io/Documentation/specification/paths
• https://oai.github.io/Documentation/specification/parameters

Links point to 'https://oai.github.io/examples/tictactoe.yaml' which currently gives a '404' response.

Referencing #59 and conversation therein...

Add a Section for Security support in OpenAPI, describing:

• The Security Scheme object and what is supported out-of-the-box.
• The security property and its application (globally, in a Path Item).
• Add nice graphvviz diagram showing where Security Scheme and security property live.

Writing style to approximate what's gone before based on mimicry rather than writing guidelines.

cc @lornajane

@MikeRalphson suggested perhaps renaming this repo on Slack yesterday, suggesting "learn" as that is the site name. I'd suggest "Learn-OpenAPI" to make the repo name more distinctive and less likely to collide when someone forks it ("Documentation" is about as generic and collision-likely as they come). "Learn-OpenAPI" also matches the capitalization of "OpenAPI-Specification", "Documentation", etc.

See OAI/OpenAPI-Specification#3185 (comment) and follow-on comments.

• format best practices
• alternative JSON schema approaches

I just noted that the 3.0-RC0 specification contains no examples where oneOf or anyOf is used (maybe also not, that is difficult to search).

Should we have some of them, as this is an new important feature?

We intentionally moved requestBodies out of the parameter array in V3 because viewing then as parameters is misleading.

https://github.com/OAI/Documentation/blob/xavi/specification/specification.md

I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:

/api?action=action1&some-param=1
/api?action=action2&other-aparam=2

If I would put all parameters under a single path, that would force all parameters under that path, too and would mix a lot of parameters that are only valid on certain actions.

The Swagger editor doesn't let me create multiple entries for the same path, even if the action parameter is required with a different value on each. and doesn't accept /api?action=action1 as a separate path either.

Is the unique path a requirement from Swagger or from the OpenAPI spec ?

Is there a good workaround how to handle this ?

Thanks!

Originally posted by @willamowius in OAI/OpenAPI-Specification#3344

From #1

• Callbacks and Webhooks [Advanced]: What’s the difference, with examples. #76
• Schemas [Advanced]: examples for schemas, responses and parameters.
• Security [Advanced]: securityScheme and security.

It would be a great addition to the spec to have:

• Tutorials from beginner to expert level (disclosure: I'm currently writing one)
• FAQs to find a quick response to a specific use case without having to dig in the spec or do the tutorials ("how do I reuse a definition", "how do I set a response header", ...)
• Standalone example YAML files (linked to tutorials, FAQs)

The proper order should be:

• Getting Started
• Introduction
• Specification Explained
• Best Practices

Edit: I've changed the purpose of this issue so it is a container for topics that would be nice to have discussed in the docs.

1. Start Here:
   • Intended Audience: Who should read this guide and why, what page to read depending on your goal.
   • Advantages of using OpenAPI: Summary of benefits obtained by using automated tools.
2. Introduction: General overview, for context. Skippable.
   • What is an API: APIs in the general case (local and remote), Specification through Documentation, Specification through a Description File (list of benefits), historical examples.
   • What is OpenAPI: Definition, types of APIs it can describe, evolution from Swagger, list of benefits, link to OpenAPI.Tools
3. The OpenAPI Specification explained: Describe the Specification in a more approachable way, with links to the actual document and constant references to the relevant Best Practices pages. Put advanced topics in this chapter to keep the TOC simple, but tag them clearly.
   • Basic structure: Minimal Hello World API description.
   • Paths Object:
   • Content:
   • Parameters:
   • Components:
   • Servers:
   • Documentation & Examples:
   • Callbacks and Webhooks [Advanced]: What’s the difference, with examples.
   • Schemas [Advanced]: examples for schemas, responses and parameters.
   • Security [Advanced]: securityScheme and security.
4. Best Practices: Suggestions that greatly simplify working with the spec even though technically they do not belong to it.
   • Keep a single source of truth: Always, no matter your workflow (Design-first, Code-first , ...).
   • How to write the description file: By hand, Editors, Domain-Specific Languages, Code annotations.
   • Do not Repeat Yourself: Reusing descriptions using $ref. Example directory structures.

I can't access the relevant settings though.

Some anchor tags don't point to a valid id on the corresponding page like https://spec.openapis.org/oas/v3.1.0#pathsObject. It should be https://spec.openapis.org/oas/v3.1.0#paths-object. Seems like the ids were switched to kebab case but some links with anchor tags were not updated in this repo.

The security page seems to have uncovered a usability issue with the site, namely the centre column is fixed width and therefore makes the security diagram look tiny (even on a huge monitor with maximised window):

It'd be good to resize this centre column so as make such diagrams clearerer without having to zoom in.

According to the OpenAPI project charter, section 7.3 , the documentation, by default, should be released under Creative Commons Attribution 4.0 International License. https://www.openapis.org/participate/how-to-contribute/governance

The SVG images contain links to OpenAPI Specification page, https://spec.openapis.org/oas/v3.1.0 .

Though, now the users end up at the top of the OAS page, without navigating to the specific section.

For instance:
At https://learn.openapis.org/specification/paths.html we have an SVG that contains links:

• https://spec.openapis.org/oas/v3.1.0#oasObject
• https://spec.openapis.org/oas/v3.1.0#pathItemObject, etc.

Correct URLs are:

• https://spec.openapis.org/oas/v3.1.0#openapi-object
• https://spec.openapis.org/oas/v3.1.0#path-item-object, etc.

This issue applies to all SVG (and DOT) files in the img directory.

Some pages contained text in two columns. I think side-by-side comparison of code samples is more readable by far, so I'd like to have this layout back:

In specification-structure.md:

In specification-content.md:

In specification-docs.md:

All reference to this layout has been removed from the source files now so I fear it will be forgotten.

All documentation links, including the "Getting Started" link on the homepage appear broken.

It is based on the README file which was only a placeholder. This page should be removed and the new landing page should be the Getting Started one.

The big logo and the note regarding the site's theme are nice, though, so maybe they can be merged into Getting Started.

Requirements from the TSC meeting:

• Accessible
• TOC always visible
• Clickable svg-files

https://oai.github.io/Documentation/start-here.html - I wanted to contribute/raise a PR for an edit on the documentation, but there is no link to a GitHub repository that would lead me here. If we're hoping for individuals to participate and contribute at least to the docs, typos or factual errors even, we could add a link to this GitHub repository.

It was two-step navigation for me personally. Let's make this easier for others?

For instance - there's an Edit button on the top of the page - https://code.visualstudio.com/docs/setup/setup-overview

It would be helpful to get a short explanation of which contexts allow which siblings to a $ref as this causes quite a lot of confusion. There's a good comment from @handrews here: OAI/OpenAPI-Specification#3526 (comment) which might give us a basis to start from.

in https://oai.github.io/Documentation/specification/content.html#the-schema-object --

Array types must have an items field, which is a Schema Object itself, and defines the type for each element of the array...
... Finally, object types must have a properties field listing the properties of the object. This field is a map pairing property names with a Schema Object defining their type.

This isn't stated in the specification (https://spec.openapis.org/oas/v3.1.0#schema-object) nor in the schema itself, so these lines should be removed, or "must" changed to "recommended" or "should".

in https://github.com/OAI/Documentation/blob/main/specification-structure.md:

The root object in any OpenAPI document is the OpenAPI Object and only three of its fields are mandatory: openapi, info and paths.

But the schema (https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.yaml) says:

anyOf:
  - required:
    - paths
  - required:
    - components
  - required:
    - webhooks

Which one is correct?

I see a few issues/PRs that have been up for months without a response. Just wondering if someone is actively maintaining this site still.

I guess because has_children == true a TOC is automatically added by the theme, but it already has one, and it's more detailed. The automatic TOC should be removed.

We get quite a few questions about callbacks and webhooks, the use cases and the differences. Add some resources to make these topics clearer.

On introduction page: https://learn.openapis.org/introduction.html
section: "API Description Using the OAS"
Link text: "the beginning of this guide"
Link: "https://learn.openapis.org/start-here"

Error link is 404 (github 404 page)