oai/openapi-style-guide

How to (and how not to) refer to the OAI in meetups, interviews, casual conversations, the settling of bar bets, and for conference presentations.

openapi-style-guide's Issues

Minor wording changes needed for readability

I am proposing some minor wording changes to the Style Guide to improve readability. According to the Development Guidelines, I am creating this issue and will make the proposed changes for your review.

Terminology explanation in README

Currently the README contains this:

Specification: for example "Can you send me your specification?" (may be abbreviated less formally as "spec")

It seems like this either refers to an older use of terms when it was ok to call a "definition" a "specification". Or if it really means that I am asking somebody to send me the OpenAPI specification, then this may not be the most helpful example. What about:

Specification: for example "My OpenAPI document conforms to the OpenAPI specification version 3.1.0"

OpenAPI Specification vs. Swagger specification - Why the change in capitalization for Specification?

I find it curious that the word "specification" is capitalized when following OpenAPI, but not when following Swagger.

I understand there exists an abbreviation OAS - but I'm not sure that the presence of a capital S in that abbreviation necessitates a capital S in "OpenAPI Specification".

Is there an explanation for why Specification is capitalized?

Organize and consolidate name & logo usage guidelines, 3rd-party branding guidelines

This Style Guide now provides some guidelines for the use of the OpenAPI name in the branding of projects, tools, and organizations outside the OAI itself, and the use of logos resembling the OpenAPI logo in such projects.

However, I had a hard time finding guidelines for appropriate usage of the OpenAPI logo itself.

It turns out that the usage guidelines seem to be in three different places:

• This OpenAPI Style Guide
  • Sourced from the README file
  • This is the only page that has the new 3rd-party branding guidelines.
• The FAQ / Style Guide page on the OpenAPIs.org website.
  • That page looks like it might have been sourced from an earlier revision of this style guide.
  • I don't see a link from that page to this style guide project on GitHub, only to the logos. The page content includes a mention of "this repository," but the page appears outside of any repository.
• The FAQ / FAQ page on the OpenAPIs.org website.
  • That page refers to (but doesn't actually link to) the Linux Foundation Trademark Usage page.
  • That page is the only one that contains requirements for trademark symbols and attribution notices, which may be important to mention in any context that describes appropriate usage.
  • That page is also the only one that describes general guidelines for appropriate use of the OpenAPI logo.
  • It also contains a guideline for third-party usage that is expressed somewhat differently from the naming guidelines in this Style Guide:

    Use is NOT acceptable if a company is stating, or implying, that OAS is a mark of an org besides the LF. For example, entities should ensure that their own product names and logos are larger than OAI/LF – OpenAPI Initiative and OpenAPI Specification should not be the most prominent name or logo on their materials.

There's quite a bit of overlap across these pages. There are likely some inconsistencies. They don't seem to be cross-linked in a methodical way. A person looking at any one of these pages probably won't know to look at the others to get the full picture. They would reasonably assume that the guidelines they see are complete and definitive.

I think we should look at this carefully and try to make it more DRY, so there's exactly one authoritative source for information about appropriate use of the OpenAPI names and logos, along with the related third-party branding guidelines.

OpenApi Icon

Can you add the OpenApi Icon to https://github.com/OAI/OpenAPI-Style-Guide/tree/master/graphics?
I would have done a PR but my SVG / AI editing skills are... mediocre at best.

I am sure that as adopters grow (as they did in the past) the open api svg icon will reach popular icon fonts projects, etc.

Typo: Style Guide does not follow style guide: "Open API Initiative" vs "OpenAPI Initiative"

On: https://github.com/OAI/OpenAPI-Style-Guide
Under: The Initiative Name and Usage
The term "Open API Initiative" is used, though in the same sentence the rules state that there should be only 1 space (i.e. presumably it should be "OpenAPI Initiative" to be in line with the format used for "OpenAPI Specification").

Grammar in initiative example

The text here is just a bit heavy-handed...

Among the concerns are the example of usage of the name of the initiative: "is are not one the same as the initiative itself."

No XML attribute generated for attribute

I have the following XML:
<xs:element name="CancelRequest" nillable="true" type="CancelRequest" /> <xs:complexType name="CancelRequest"> <xs:sequence> <xs:element minOccurs="1" maxOccurs="1" name="OrderID" type="xs:string" /> </xs:sequence> <xs:attribute name="version" type="xs:string" /> </xs:complexType>
The corresponding Java class has ben generated using xjc:
`@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "CancelRequest", propOrder = {
"orderID"
})
@XmlRootElement(name = "CancelRequest")
public class CancelRequest
implements Serializable, ToString
{

private final static long serialVersionUID = -1L;
@XmlElement(name = "OrderID", required = true)
protected String orderID;
@XmlAttribute(name = "version")
protected String version;

rest of class are getters and setters`

The code generated by Swagger is
"CancelRequest": { "type": "object", "required": [ "orderID" ], "properties": { "orderID": { "type": "string", "xml": { "name": "OrderID" } }, "version": { "type": "string" } }, "xml": { "name": "CancelRequest" } },

There are no XML Object values generated for version. I would have expected here:
"xml": { "attribute":true }
Since version is an attribute.

Button to validate/download OpenAPI spec?

Is there OpenAPI analogue to the Swagger validate button? Or currently the Swagger one should be used?

Specification not easy to discover on openapis.org

When I search for "openapi specification" I will get https://www.openapis.org/ as first result, I go to the website and there is no obvious link to the specification. There is a Specification button, but it's only a menu. I am expecting a direct link to https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md or better yet a smarter presentation than an md file such as https://swagger.io/specification/

"Guidelines for Naming Projects, Tools, or Organizations" section in the readme

With commit 7687728 a new section "Guidelines for Naming Projects, Tools, or Organizations" was introduced in the README. This issue is about understanding the consequences.

---

Found on GitHub:

GitHub Organization:

Several GitHub Organizations are already using OpenAPI as prefix:
https://github.com/OpenAPI
https://github.com/OpenApiFactory
https://github.com/OpenAPITools
https://github.com/OpenAPI-Tools-Automation
https://github.com/openapi-test
https://github.com/openapi-ro

Project name:

Several GitHub projects are already OpenAPI or openapi in their project name:
https://github.com/contentjet/openapi-ui
https://github.com/getkin/kin-openapi
https://github.com/oasis-tcs/odata-openapi
https://github.com/Mermade/openapi-codegen
https://github.com/Mermade/openapi-filter
https://github.com/Mermade/swagger2openapi
https://github.com/Microsoft/OpenAPI.NET
https://github.com/openapitools/openapi-generator
https://github.com/p1c2u/openapi-spec-validator
https://github.com/quen2404/openapi-diff
https://github.com/RepreZen/KaiZen-OpenAPI-Editor
https://github.com/RepreZen/KaiZen-OpenApi-Parser
https://github.com/xuzhg/OData.OpenAPI

Is the usage of open-api in the project URL better?
https://github.com/eclipse/microprofile-open-api (Project title in the readme: "Eclipse MicroProfile OpenAPI")
https://github.com/janephp/open-api (Project title in the readme: "Jane OpenAPI"

And some projects are using openapi3:
https://github.com/metadevpro/openapi3-ts
https://github.com/adwhit/openapi3-rust

---

While I understand the concern about the usage of the OpenAPI brand in third-party projects, I think that the rule as formulated in the readme is really hard to implement. There are a lot of projects out there (small one, big corporation one, foundation-backed one). I think that the having a lot of projects having adopted "OpenAPI" in their project names demonstrate the strength of the ecosystem.

Thank you in advance for your advises on how to read the section.