docs: inital WIP commit of docs #1

TristanSpeakEasy · 2023-06-02T14:50:30Z

Please feel free to use the suggestion feature of Github and provide suggestions for changes to the content here.

Also seeking early feedback for structure and specific information I should be calling out in regards to our product.

My early pass on this will likely be mirroring the official spec mostly before I do a second pass and try to add similar additional information to the swagger docs

This is not intended to be the final format of the documentation (We will likely have a much more complex MDX or even better formatted website with lots of interactivity I would imagine), this is just meant to be an initial structure and creation of content for our own OpenAPI documentation.

VIEW THE ACTUAL DOCUMENTATION HERE: https://github.com/speakeasy-api/openapi-reference-documentation/blob/initial-draft/README.md

zostay

I enjoy your writing here. It's not too formal and not too conversational. The tone is very even and doesn't feel foreign (as writing by folks across either pond sometimes do). It is easy to follow what your saying and you convey that what you're saying is interesting and important to you.

I'd like to see the introduction lay out what the document is attempting to accomplish and it's philosophy. This will probably change as you write and doesn't need to be present at this point in the writing, but I find it helpful when the author(s) of orient my expectations and help me understand why they felt a need to write the document and what they hope to accomplish that sets it apart. It is also helpful to layout a thesis that describes how the document is laid out to set the expectation as to the structure of the document and how each section will generally work, etc.

From the name of the repo, I expect this document to be reference documentation, but the intro feels more like a guide. That expectation could be aided with a thesis/summary section as I've mentioned above. When I'm learning a new tech, I usually like to start with some sort of guide, which is mostly prose, typically with embedded tutorials and examples. Then, as I become familiar with it, I move over the reference, often not finishing the guide (I'm in a hurry and I'm a slow reader), and just refer to that from there on. Sometimes, documents attempt to be a little of both, which can also work. Anyway, some of my commentary is based on not yet knowing what your intensions are as the document is still in a very early drafty form.

Your writing is, except where I've noted, very readable and doesn't feel formal to me. It leans a little heavily into tables and code at this point, but that's what you'd expect from a reference, so I don't know that that's actually a criticism or just me wanting something with more guidance and less reference at this point.

This is an excellent start. I look forward to reviewing it further as you make progress over the next few weeks.

README.md

zostay · 2023-06-12T15:22:47Z

README.md

+### How does this documentation differ from the official OpenAPI documentation?
+
+`TODO`
+


I think it would be useful to have a section between Introduction and The Document that covers the needs of APIs in general. We don't have to be too basic, but use it as a way to introduce and define the jargon we're going to use in this document and also provide a general notion of what an API needs some kind of specification at all. This can also be an opportunity to discuss the difference between an APIs as an abstract construct, the implementation of it on the server, and the client SDKs used to access it. No more board than necessary to carry the rest of the document forward, but broad enough to cover what we care about at Speakeasy and to understand how OpenAPI works in the abstract.

This could also be a good place to introduce the API we're going to be using in the examples and use that to make the abstract description of APIs into a concrete idea:. For example, you could describe a particular API endpoint and it's purpose is, show how it would be implemented on the server side in Python, and then a basic handwritten SDK client caller of some kind, maybe using JavaScript.

Anyway, something more general, but still with some concrete bits to keep it grounded might be a good place to introduce topics and jargon the reader will need to understand later and may or may not have experienced before, depending on their experience level with APIs.

Yep great idea and I totally agree, @ndimares I think you might be better placed to write
something like that for this, but if not I will definitely get round to it

README.md

zostay · 2023-06-12T22:07:03Z

README.md

+
+```yaml
+servers:
+  - url: https://{organization}.{environment}.speakeasy.bar


Ideally, we ought to own speakeasy.bar or whatever we use as the domain name in the examples. It would be best if there was an actual API at the host location that actually worked at that location. Otherwise, we should stick to example.com for references. According to my usual domain registrar, and to my astonishment, this domain appears to be available for $409 with a $585 renewal.

@simplesagar can we do that? Buy https://speakeasy.bar and then yeah I think it would be pretty cool to host a usable API there that is just a mock for matching the document, will just need to be a bit more careful in making sure the examples are actually reflective of real world usage

I believe @simplesagar has now purchased this?

zostay · 2023-06-12T22:08:55Z

README.md

+        sdk.sdkConfiguration.ServerIndex = serverIndex
+    }
+}
+```


It might be better to select a language like Python for the codegen examples as it has a wider adoption and is generally more familiar to people than Golang.

So I just did Golang for now as I can write it really easily without too much back and forward reference checking, but what I would eventually like to see is us having tabs for each language we support and examples in all the languages

zostay · 2023-06-12T22:10:40Z

README.md

+    speakeasy.WithEnvironment(speakeasy.ServerEnvironmentStaging),
+    speakeasy.WithOrganization("speakeasy"),
+)
+```


This is a long enough Speakeasy tip that I almost feel a blog post would be a good idea and just link off to that or something.

So the SDK Generation examples will largely be "pop out" example ie they will be hidden behind an accordion expansion section or similar and are only shown when the user clicks on them, so the intent is not to have them inline like this

But there could also be an argument for two (or more) different documents that just link back and forward to one another.

Information/documentation structure is something we should definitely discuss and get maybe some feedback on from a design agency etc.

For now the purpose of this is to largely write the content so it is then available for us to build our perfect OpenAPI documentation from.

zostay · 2023-06-12T22:14:57Z

README.md

+
+The above example requires both an API Key **AND** Basic Auth to be provided.
+
+This **AND**/**OR** logic along with optional (`{}`) security can be used in any combination to express complex authorization scenarios.


What if I have an API where a handful of the endpoints require no security, but the rest require some security?

For example, perhaps I provide an auth endpoint that generates a security token from some other shared secret or passkey or something that must be passed to the other endpoints.

How would that situation be handled?

I feel like this document is going to require a large security section with examples of the four or five most common cases because security is so fundamental to APIs.

Added more examples let me know what you think

…dback

…ions

TristanSpeakEasy · 2023-06-13T10:05:40Z

From the name of the repo, I expect this document to be reference documentation, but the intro feels more like a guide

So the main purpose of this document is to be reference documentation but I wanted to include enough concrete examples and explanations that the reader leaves with a good understanding of how things work. In my eyes the main problem with the official documentation is it is too light on concrete details and then the swagger documentation is the opposite it doesn't have enough reference documentation, so I want ours to straddle the line of balance between both.

TristanSpeakEasy · 2023-08-10T09:57:36Z

README.md

+### What is OpenAPI and why use it?
+
+`TODO`


@ndimares help would be appreciated on the content for this section

TristanSpeakEasy · 2023-08-10T09:57:43Z

README.md

+### How does this documentation differ from the official OpenAPI documentation?
+
+`TODO`


@ndimares help would be appreciated on the content for this section

WIP Add to OpenAPI document, add validation, some writing

TristanSpeakEasy added 2 commits June 2, 2023 14:48

docs: inital WIP commit of docs

d77eb79

wip

0fa6c58

TristanSpeakEasy marked this pull request as draft June 2, 2023 17:18

wip

2cb1f8d

TristanSpeakEasy requested review from ndimares and simplesagar June 8, 2023 14:02

zostay reviewed Jun 12, 2023

View reviewed changes

TristanSpeakEasy added 3 commits June 13, 2023 08:44

fix: addressing grammar, structure and small content changes from fee…

f6bf144

…dback

fix: add example of how fragments can be used to create unique operat…

355ebf7

…ions

fix: provide more security examples

89c35bc

TristanSpeakEasy added 2 commits June 13, 2023 10:25

wip

7459289

wip

9b036d2

simplesagar requested review from ThomasRooney, alexadrake and anuraagnalluri June 16, 2023 00:45

TristanSpeakEasy added 4 commits July 3, 2023 06:34

wip

bac0931

wip: add parameter documentation

868ee7b

wip: add details about alternative openapi features for parameters

dd2c58a

wip

19d2384

TristanSpeakEasy commented Aug 10, 2023

View reviewed changes

TristanSpeakEasy added 4 commits August 10, 2023 10:25

wip

fd1f08b

wip

182fb67

wip

7a855ad

wip

f46395d

sixhobbits added a commit that referenced this pull request Jan 31, 2024

Merge pull request #1 from ritza-co/niel/wip-init

3674fae

WIP Add to OpenAPI document, add validation, some writing

ndimares marked this pull request as ready for review March 1, 2024 14:58

ndimares merged commit 20c6e2a into main Mar 1, 2024

		### How does this documentation differ from the official OpenAPI documentation?

		`TODO`


		The above example requires both an API Key AND Basic Auth to be provided.

		This AND/OR logic along with optional (`{}`) security can be used in any combination to express complex authorization scenarios.

docs: inital WIP commit of docs #1

docs: inital WIP commit of docs #1

Uh oh!

Conversation

TristanSpeakEasy commented Jun 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zostay left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TristanSpeakEasy Jun 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TristanSpeakEasy commented Jun 13, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TristanSpeakEasy commented Jun 2, 2023 •

edited

Loading

TristanSpeakEasy Jun 13, 2023 •

edited

Loading

TristanSpeakEasy commented Jun 13, 2023 •

edited

Loading