guide: migrate from swaggerhub (bump-sh#239)

* guide: migrate from swaggerhub

* pr feedback

* updated image

* fixed formatting in postman guide to match

* updated tutorials to use date frontmatter

src/_guides/bump-sh-tutorials/migrate-from-swaggerhub.md

@@ -0,0 +1,94 @@
+---
+title: Migrate from SwaggerHub
+authors: phil
+excerpt: Move your OpenAPI out of SwaggerHub and into your own source control, so you can control more of the workflow with all the same benefits.
+date: 2024-06-25
+---
+
+Tools like SwaggerHub provide an editing and hosting experience for OpenAPI documents, allowing teams to fork APIs, add new versions, diff, and compare, which was pretty handy back in the day. These days it can feel like recreating Git with a walled-garden, needing to be imported and exported, or joined together with "integrations" that involve manually setting up webhooks to ping your other tools when there are changes. Many teams are starting to question how useful that is.
+
+Bump.sh gives teams more flexibility in how they work, but the most common workflow assumes that your OpenAPI is your source of truth, and that source of truth lives with the source code in Git, so instead of managing source code and OpenAPI separately you have it all in the same pull requests as you go. Your documentation can still be published immediately on changes, but it all happens from your Git repository or CI/CD setup as a central point, instead of being stuck in somebody elses server.
+
+## Step 1: Export OpenAPI from SwaggerHub
+
+To liberate your OpenAPI from SwaggerHub for good, head to "My Hub", open each API one at a time, then click "Export" > "Download API" > "YAML Unresolved".
+
+![](/images/guides/migrating-from-swaggerhub/export-from-swaggerhub.png)
+
+This will download a version which still has `$ref`'s, which will keep the file size smaller and avoid duplication of components.
+
+Now pop the downloaded OpenAPI into your source code repository, and give it a tidy name in the process.
+
+```
+mv ~/Downloads/ME_10-train-travel_api-1.0.0-swagger.yaml ~/src/train-travel-api/openapi.yaml
+```
+
+Now you can add this OpenAPI to your source control, which assuming Git is a case of:
+
+```
+cd ~/src/train-travel-api
+
+git add openapi.yaml
+
+git commit -m "docs: imported openapi"
+```
+
+## Step 2: Setting up an OpenAPI Editor
+
+One thing that SwaggerHub does well is providing an OpenAPI editing experience. Users write YAML/JSON in an editor window on the left, and see a preview of that OpenAPI as documentation on the right. This gives new users of OpenAPI more confidence, because they can see their changes as they work on it.
+
+Using open-source tooling can provide this exact same experience, easier, cheaper, and more powerful, without needing to pay for a hosted service. Whatever your favorite IDE or text-editor, there's an OpenAPI extension you can use to bring in that preview experience on your development machine. 
+
+### VS Code OpenAPI Extension
+
+[VS Code](https://code.visualstudio.com/) users have a variety of popular extensions to chose from.
+
+- [OpenAPI Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) by 42Crunch - code navigation, linting, SwaggerUI or ReDoc preview, IntelliSense, schema enforcement and generation, schema definition links, snippets as well as static and dynamic security analysis.
+- [OpenAPI Preview](https://marketplace.visualstudio.com/items?itemName=zoellner.openapi-preview) by Andreas Zoellner - Preview panel using Stoplight Elements.
+- [OpenAPI Viewer](https://marketplace.visualstudio.com/items?itemName=AndrewButson.vscode-openapi-viewer) by Andrew Butson - Preview panel using RapiDoc.
+
+The OpenAPI Editor from 42 Crunch is a powerful choice, offering not just a preview panel but auto-complete and a "explorer" view to help you move around the OpenAPI document. It also has a choice of preview tools, with Swagger UI being the exact same tool used on SwaggerHub. 
+
+![](/images/guides/migrating-from-swaggerhub/42crunch-openapi-editor.png)
+
+The other tools offer just a preview experience, but offer two alternative open-source OpenAPI rendering tools to give you a few options in how you look at the OpenAPI as you go.
+
+### JetBrains IntelliJ
+
+The JetBrains team clearly recognize the importance of OpenAPI to their IntelliJ, PhpStorm, RubyMine, etc. community because they've created an official extension: [Jetbrains OpenAPI Specifications](https://plugins.jetbrains.com/plugin/14394-openapi-specifications).
+
+![](/images/guides/migrating-from-swaggerhub/jetbrains-openapi-specifications.png)
+
+The 42Crunch team have also built an extension: [OpenAPI​ Editor](https://plugins.jetbrains.com/plugin/14837-openapi-swagger-editor) will provide IntelliSense, "Go to Definition" for `$ref`, and the usual preview showing SwaggerUI or ReDoc.
+
+### Other Editors
+
+Check on [OpenAPI.Tools](https://openapi.tools/) to find more editors with OpenAPI preview functionality like Eclipse and Vim. 
+
+If there are no OpenAPI preview tools for your editor of choice, you can open up a browser window and use the [Bump.sh CLI](https://github.com/bump-sh/cli)'s `preview --live` command to see how changes look as you work on your document.
+
+```
+$ bump preview openapi.yaml --live
+
+* Let's render a preview on Bump... done
+* Your preview is visible at: https://bump.sh/preview/4a478f7d-8776-4c43-bc01-cf58dd7dd5f5 (Expires at 2024-05-29T16:17:06+02:00)
+Waiting for changes on file openapi.yaml......
+```
+
+## Step 3: Publish OpenAPI as Documentation
+
+Instead of having to click around a web interface to fork versions, "commit" changes in a web interface, make sure the changes are published, etc. Bump.sh allows you to automate the changes. 
+
+You can set up your documentation to deploy [using the command-line](https://docs.bump.sh/help/continuous-integration/cli/), with the [Bump.sh GitHub Action](https://docs.bump.sh/help/continuous-integration/github-actions/), or using any other [Continuous Integration setup](https://docs.bump.sh/help/continuous-integration/ci/) you like. There's even an API for [more exciting deployment integration opportunities](https://docs.bump.sh/help/continuous-integration/api/). 
+
+A common workflow is to have Bump.sh make previews on Git branches, then deploy the main version of the documentation when a branch is merged. This allows you to defer all configuration about how reviews work, what checks should be involved, who is in charge of approving changes, etc to the pull request settings of your source control. 
+
+![](/images/guides/migrating-from-swaggerhub/bump-pull-request.png)
+
+Once a guide is published you can view the hosted documentation on Bump.sh, and it will look a little something like this: [Train Travel API Documentation](https://bump.sh/bump-examples/doc/train-travel-api).
+
+Once you've done this for all of your APIs and got them publishing on commit, you can close down your SwaggerHub account and update links to your API documentation.
+
+## Step 4: Use Hubs to Group Your APIs (Optional)
+
+If you had your APIs grouped into different organizations you can either make multiple Bump.sh organizations, or you can use [Hubs](https://docs.bump.sh/help/hubs/) to group APIs together.

src/_guides/bump-sh-tutorials/try-requests-in-postman.md

@@ -0,0 +1,107 @@
+---
+title: Try HTTP Requests with Postman
+authors: phil
+excerpt: Integrate your OpenAPI-powered documentation with Postman to let customers try your API out, right from the API docs.
+date: 2024-05-14
+---
+
+Seeing how an API works is the first step in an end-users journey to using the API, and the second step is making some test requests to get a feel for how it works. Some people like to do this with code, so code samples will be a good start for them, especially if you have an SDL. Other people like to do this with interactive HTTP clients, like [Postman](https://postman.com/).
+
+Postman is one of the original modern API consoles. Users can create or import "collections" which are very similar to OpenAPI but focus more on actual requests and responses being saved, like a whole bunch of bookmarks in a browser. Those collections can be distributed in various ways, and it's becoming increasingly common for API providers to publish a read-only public Postman Collection for end-users to download, so they have a whole interactive API console ready to go.
+
+This guide will go through getting started with Postman, creating a "Postman Collection" from the same OpenAPI that powers your documentation, to finally getting a "Run in Postman" button into your Bump.sh API docs.
+
+## Step 1) Install Postman
+
+[Download](https://www.postman.com/downloads/) and install Postman on your computer and load it up.
+
+## Step 2) Create a Postman account
+
+Create a new account (it's free). If you're doing this for a business or organization other than yourself you can create a workspace your collections to live in.
+
+![Create your workspace view, with a list of templates that can be used for the workspace, "API demos" template is selected.](/images/guides/try-requests-in-postman/postman-create-workspace.png)
+
+## Step 3) Connect your API to Git version control
+
+On the left sidebar click APIs, and you should see the option to create a new API. If this option is missing open up Workspace settings and configure the sidebar to add the APIs option.
+
+The APIs interface will show you have no APIs, so click "Create" and give the API a name.
+
+!["New API" screen in Postman, showing "Quickstart your API by connecting a repository" and a list of options to connect GitHub, Bitbucket, GitLab SaaS, or Azure DevOps.](/images/guides/try-requests-in-postman/postman-new-api.png)
+
+Then you can configure which Git repository your API should be connected to.
+
+!["Connect Repository" screen in Postman, with dropdowns for GitHub organization, Repository, and initial branch.](/images/guides/try-requests-in-postman/postman-connect-repository.png)
+
+Next, point Postman to the "API schema file", which is their way of saying "API description document." Whatever you call it, this is the same `openapi.yaml` document that you use to deploy to Bump.sh.
+
+It's possibly sat in the root of your repository, but if you're not sure, you can look at your `.github/workflows/bump.yml` and see where the deploy command is looking for the `file: {filename}`. 
+
+Click "Connect Repository" when it's all done and you'll be taken to the API overview page.
+
+## Step 4) Setup Postman in the Repository
+
+Before you can publish this API to the world, we need to help Postman identify the specific API being described. If you hover over the Publish button it will suggest some changes, which it can commit for you.
+
+![Postman source control view with some changes it wants to make, and a warning to commit to a branch as main branch is protected.](/images/guides/try-requests-in-postman/postman-commit.png)
+
+Click the commit button and then create a pull request, ideally through the Postman "Create pull request" button on the same screen. It will take you to your Git hosting provider on the pull request page. The pull request contains a few bits of config, like the Postman API ID. 
+
+If you'd like to see what it looks like, take a look at the [Train Travel API pull request](https://github.com/bump-sh-examples/train-travel-api/pull/17/files ), or jump right in with your API. 
+
+When this is done, Postman will be all set up to work with your API in your repository.
+
+## Step 5) Generate a Postman Collection
+
+Postman is now aware of your OpenAPI document, but in order to share a collection you'll need to generate a collection from your OpenAPI.
+
+![Postman's API overview lists "Definitions" with the one we just added, and "Collections" which is empty, but has an option to Generate from definition](/images/guides/try-requests-in-postman/generate-from-definition.png)
+
+Clicking "Generate from definition" you'll see a modal window with a whole bunch of options. To start off just keep them all default, perhaps changing the Parameter Generation setting to Example if your OpenAPI happens to have great examples in there already.
+
+![Genereate from definition settings on their defaults, mainly Naming requests set to Fallback](/images/guides/try-requests-in-postman/generate-modal.png)
+
+Almost done! The collection lives in the APIs panel under our API, but in order to use the full power of Postman we need to copy it over to the main Collections tab.
+
+![The API definition contains the collection, but it needs to be copied to Collections tab by right clicking and selecting Copy to collections](/images/guides/try-requests-in-postman/copy-to-collections.png)
+
+## Step 6) Integrate the Run in Postman button to Bump.sh
+
+Finally, this collection is ready to rock, and we can embed the Run in Postman button into our Bump.sh documentation. 
+
+To get the button, click on the collection and find the Share option, then select the Mxarkdown version.
+
+![Share modal, Via Run in Postman tab selected, with the Markdown friendly tab within that.](/images/guides/try-requests-in-postman/postman-share-button.png)
+
+Take that Markdown, and pop it into your OpenAPI somewhere. The easiest place to put it is right in the `info.description` property. 
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Train Travel API
+  description: |
+    API for finding and booking train trips across Europe.
+
+    ## Run in Postman
+
+    Experiment with this API on Postman, using our Postman Collection.
+    
+    [<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://app.getpostman.com/run-collection/9265903-7a75a0d0-b108-4436-ba54-c6139698dc08?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D9265903-7a75a0d0-b108-4436-ba54-c6139698dc08%26entityType%3Dcollection%26workspaceId%3Df507f69d-9564-419c-89a2-cb8e4c8c7b8f)
+```
+
+> A better place for this button might be a [dedicated Topic](/help/enhance-documentation-content/topics/), using the `x-topics` extension supported by Bump.sh documentation.
+{: .info}
+
+To see how this looks in Bump.sh before pushing it live, you can use the Bump.sh CLI's `preview` command.
+
+```
+npx bump-cli preview openapi.yaml --live
+```
+
+The command will return a link, click that and see how the documentation looks.
+
+![Back in the Bump.sh hosted API documentation we've added a "Run in Postman" section with the paragraph added in Markdown above, and the orange Run in Postman button showing](/images/guides/try-requests-in-postman/bump-docs-postman-button.png)
+
+When you (or your users) click the new Run in Postman button, they'll be able to view the original, or fork the collection to their own workspaces to customize the requests for their own needs. When it loads up, the collection will show all the possible requests, and help them add the right headers, parameters, and authorization details.
+
+![The view Postman users will get after clicking that button, with the Train Travel API example, and operation Get a list of train stations selected ready for HTTP requests](/images/guides/try-requests-in-postman/postman-view.png)