Topics to document

[segfaultxavi]

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.

[earth2marsh]

Consider "Who should read this guide?" with a brief description of what they'll learn when they're done.

Possibly break out from "What is the OpenAPI Specification" into a representative sample of the value you can then derive from tooling with "What can you do with an OpenAPI spec?" [NB: I tend to use Specification with a capital S when talking about the description format and to use spec when talking about an OAS document. Others might prefer another convention, of course!]

Consider addressing schemas in the basics? Since the primary goal is to get new people to a level of basic competence, consider deferring the more advanced topics until later, and to focus the best practices on those new to working with specs.

Because code-first will vary across languages, it might be sufficient to mention that workflow approach but focus more on hand-written specs. Similarly, it's worth pointing out that specs could be analyzed for standards compliance, but that that's a tooling benefit addressed outside this document.

[segfaultxavi]

Consider "Who should read this guide?" with a brief description of what they'll learn when they're done.

I like doing this at the beginning of each page, but I agree having a global one could be beneficial. Thanks.

Possibly break out from "What is the OpenAPI Specification" into a representative sample of the value you can then derive from tooling with "What can you do with an OpenAPI spec?"

The way I have approached the introduction so far (will share soon), I talk about the befits of APIs in general, then of API descriptions, and then of OpenAPI. Maybe it will make more sense once I share it and we can continue discussing it in the PR.

[NB: I tend to use Specification with a capital S when talking about the description format and to use spec when talking about an OAS document. Others might prefer another convention, of course!]

Good to know there's at least a convention :) Might borrow yours...

Consider addressing schemas in the basics? Since the primary goal is to get new people to a level of basic competence, consider deferring the more advanced topics until later, and to focus the best practices on those new to working with specs.

I have no idea yet what schemas are. I put them in section 2 because @philsturgeon requested them and they seemed more related to the Specification itself than to Best Practices. I see no issue in having a new section called "Advanced topics" or similar.

Because code-first will vary across languages, it might be sufficient to mention that workflow approach but focus more on hand-written specs. Similarly, it's worth pointing out that specs could be analyzed for standards compliance, but that that's a tooling benefit addressed outside this document.

Cool, noted. Thanks.

[segfaultxavi]

I updated the proposed TOC taking @earth2marsh's comments into account.

[MikeRalphson]

[NB: I tend to use Specification with a capital S when talking about the description format and to use spec when talking about an OAS document. Others might prefer another convention, of course!]

I would (somewhat) strongly advise not to overload the term spec or specification at all. The Specification, specification or spec should be reserved for the OpenAPI Specification itself. The term we use within the OAS for an instance of the OAS is an OpenAPI document, though others may prefer definition, description or contract. @philsturgeon has a useful resource here.

This NordicAPIs blog posting is also probably good reading.

Security: Is this a Best Practice or is there syntax in the Specification regarding security?

The Specification defines securitySchemes which are the security mechanisms used by the described API, and security objects which apply those mechanisms (possibly in combinations) to specific parts of the API.

We might want to have a short section or some box-outs which highlight features new in v3.1 of the specification.

• https://www.openapis.org/blog/2020/06/18/openapi-3-1-0-rc0-its-here
• https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

[MikeRalphson]

Describe the Specification in a more approachable way, with links to the actual document

If you would find a rendered version of 3.1-rc0 (like this http://spec.openapis.org/oas/v3.0.3.html) helpful, just let me know and I will generate one you can create placeholder links to.

[segfaultxavi]

I would (somewhat) strongly advise not to overload the term spec or specification at all. The Specification, specification or spec should be reserved for the OpenAPI Specification itself. The term we use within the OAS for an instance of the OAS is an OpenAPI document, though others may prefer definition, description or contract.

This convention seems clearer to me. Accepted.

@philsturgeon has a useful resource here.

Oooohhh... this is handy, since we're definitely talking about educational material here. Thanks.
Also, I'm starting to think we might need to add a Glossary page to the docs too, or maybe just directly reference this resource.

This NordicAPIs blog posting is also probably good reading.

That actually seemed to confuse me more... but I think in the end it agrees with the definitions in openapi-glossary.

The Specification defines securitySchemes which are the security mechanisms used by the described API, and security objects which apply those mechanisms (possibly in combinations) to specific parts of the API.

So the Specification has security-related syntax and therefore it should be explained in chapter 3 (The OpenAPI Specification explained). Understood.
Further questions: Are there enough security-related hints outside what's already in the Spec to require a Security page in the Best Practices chapter?

We might want to have a short section or some box-outs which highlight features new in v3.1 of the specification.

Box-outs are more comfortable, since the reader finds them in the place were they are most relevant. But I wouldn't use a full-blown box-out (with an outline and a different background color) since they will accumulate over the years and become distracting.
My preference is to have integrated text (possibly with a ⚠️ icon) stating any difference between versions, and do not talk about the "new" version (since that adjective will become obsolete at some point).

If you would find a rendered version of 3.1-rc0 (like this http://spec.openapis.org/oas/v3.0.3.html) helpful, just let me know and I will generate one you can create placeholder links to.

OK, thanks. At this point I still don't know how I'll handle this but I guess I can link to https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md and later sed to point to the official new place?

[MikeRalphson]

Closing in favour of #59 - thanks all.