24.1214 (Gdrive)

Development on local machine. Main steps (use ChatGPT/Copilot whenever possible):

• 1.2 API only. Adding an API to starter code. Starter code is usually generated using CLI or Vercel, Netlify, etc.
• 1.3 (API +) API-doc. Adding API docs (Swagger) to the code.
• 1.4 Swagger. (TODO) Detailed examples of OpenAPI/Swagger coding.
• (1.5 API todo) (my notes)

---

GraphQL basically does the following (my understanding; if I am correct, then I dont understand why I never seen such a straightforward description anywhere, especially from official GraphQL docs):

• The query tool is used to create a query that specfies a tree of only the objects needed.
• Query is sent to the Apollo server.
• Apollo server executes the REST commands required to get all the required objects.
• Apollo "distills" the content to send back to the query tool

Postman is used to test the API endpoints. Postman is like a browser that allows you to control things "under the hood". Postman can

• Send URL requests like the browser
• View and control request/response parameters (like browser F10 dev tools)
• Main a history of commands (like browser history) and request/response details

---

• Design APIs first with Swagger before coding (no one does this).

• Create (basic) APIs.
• Create API definitions / schemas from code.
• Publish API docs (hosting sites, Railway, AWS, Gitbook, Heroku, etc).

The following has been the typical workflow for my recent projects:

1. Collect the existing API docs (what little existed).
2. Learn the API hands on (using Postman/Swagger) with minimal assistance.
3. Make my work available internally (usually via simple a tool like a Github wiki).
4. Create hands-on quick start / getting started docs (with examples, examples, examples).
5. Create a conceptual explanation of the big picture.
6. Create a sanitized/obfuscated version of API (generate from code or (my preference) edit the swagger file directly).
7. Publish the API (first internally, then externally) in something like Gitbook, a React app, etc.

The API docs I created provided details about the options, workflows, and prerequisites for endpoints. Documenting special cases that often are difficult to specify with just a swagger file.

All projects were successful. However

• Published output was only made available to customers (not public) or the product failed.
• My working docs were the confidential property of the client.
• I did not record the details of what I did. That last day on the project always came much quicker than I expected.

---

24.0930 Add these

• (19.09!/GIT/2400) Autogenerating Swagger Documentation with Node & Express Beyond Hello World https://www.youtube.com/watch?v=apouPYPh_as
• (21.01/GIT/2500) NodeJS Swagger API Documentation Tutorial Using Swagger JSDoc Maksim Ivanov https://www.youtube.com/watch?v=S8kmHtQeflo
  
• Johson https://tomjohnson1492.gitbooks.io/documenting-rest-apis/content/publishingapis/pubapis_swagger_intro.html

• Demos (my step-by-step hands-on examples)
• Concepts (with diagrams)
• Hands-on examples for various toolsets (Gdrive docs):
  • **63.1 API only. These are API server examples that do not include API docs.
  • 63.2a API + (built-in) doc. Creating API servers that include Swagger.
  • 63.2b Doc only. APIs with no API server (Sphinx, etc).
  • 63.3 GraphQL
  • 63.4 Test (Postman)
  • 63.5 Doc only deploy. For example, Swagger to Gitbook, NodeJS with Swagger to Railway.
  • **63.6 API deploy (maybe + built-in doc). Deploying API servers (usually with docs).
  • **63.7 Other (PyPi, SDKs, etc)
• 63.X Notes

** API tools (FastAPI, Flask, etc) and SDKs are included in this part although they are not documentation. I will probably move these to a new part in this wiki at some point in the future.

The ZiptieAI drone wiki provides something that I could not find elsewhere in the internet: A complete basic set of "getting started" docs for the core workflows for building AI drones. This part (63) was originally meant to show only the basics for (creating and) documenting APIs used in drones.

However, I decided to try to create more comprehensive coverage of API documentation, far beyond what is needed for simple drone projects. There are 2 reasons for this:

• My job search focuses on API doc projects.
• I need to demo my API doc expertise.

I need to demo my expertise (and working style) using this site because the deliverables for contract jobs I recently worked on (1) were not made public and (2) were not 100% examples of my own work. For example, in a recent contract job I created a full set of API documents that included a 5000 line Swagger file that I created manually (I could not edit the code base) based on a large Postman collection of my own extensive API tests. The docs and the Postman tests should have been the most complex part of the doc project. But by far the biggest challenge was working with Archbee, the API doc publishing tool the customer selected (Archbee is not in the list of docs tools on this wiki). The resulting API docs were not something I would claim as my own work.

The right choice of API doc tools is critical. In this part I

• demo a lot of API doc tools,
• describe (my understanding of) basic API concepts, and
• (future) recommend what to use.

AI tools (such as ChatGPT and Copilot) are also important API doc tools. For example, in the docx 63.1_#45_nodejs_swagger_gpt_codemify, GPT (ChatGPT) provided excellent directions (simple numbered steps for core workflow examples, something official product documentation for some reason rarely provides).

Getting a bit distracted with some other topics. AWS, networking. Not really a part of API docs.

Filenames are _#1xx...docx