![]() ![]() This would also a good time to connect the project to the GIT repository system of your choice and make an initial push. If everything renders correctly in the browser, we can move on to connecting this to our definition repository. NPX will take care of building out the base project, you can verify that everything went smoothly by moving into the new project folder and starting up the default app. ![]() To get started, navigate to the parent folder that will house your project and run npx create-react-app oas-doc-portal ![]() This gives us all our dependencies and base structure in a single command. Instead of putting together an entire React development environment we will use the create-react-app project as a starting point. Verify that you have a node version later than 5.2.0 installed by running node -v as we will be using npx to build out our initial starting point. The goal here is to do this with as little configuration as possible to leave our deployment options open, so we will only have a single requirement to start: NodeJS. Later in the series we will look at deploying this to an external host, or running inside a container - but for now lets just get it running locally. Now that we understand the tools we will be using, lets ensure we have the required dependencies to build the project. By using a tool like SwaggerHub, we can update and define our ‘current’ specifications to be shown to API consumers, while also support ongoing design and development. It plays nicely with the idea of having multiple different APIs managed by a single organization or team, and we can use its back end to load these in as needed to our documentation portal. SwaggerHub is a platform solution built by SmartBear from the ground up to support OAS at scale. We will leverage the node package provided by Swagger UI in our single page application. It has long been used in parallel to definitions as a way to quickly provide interactive documentation through minimal set up. Swagger UI lives under the Swagger tool set, a collection of open source projects that support working with OAS. Upcoming changes and test requirements can be communicated earlier as a plan exists for everyone to work against. Standards like OAS help facilitate a ‘design-first’ or ‘definition-driven’ development strategy, letting stakeholders plan out an API and its functionality before digging into code. The specification recently saw the release of its 3.0 version, and the adoption and support has continued to grow across the industry. The OpenAPI Specification (OAS) is a REST definition standard, maintained by the OpenAPI Initiative - part of the Linux Foundation. What is OpenAPI, Swagger UI, or SwaggerHub? The steps are intended for those with some familiarity with React and OpenAPI, but they should be straight forward enough to follow for those new to the tooling as well.Ī template version of the final portal can be found HERE to kick start this project, and a running example can be found hosted HERE. SwaggerHub will act as our host for the API specifications although later the series will explore alternative options for loading them. Further parts of this series will focus on smaller pieces of functionality - such as enhancing documentation with ‘walk through’ style pages, or connecting to privately hosted definitions. In this series, we will look to create a solution by passing OAS definitions into Swagger UI dynamically using React.js (Part 1), customizing this basic portal (Part 2), and finally deploying to external hosts (Part 3). Well designed and maintained documentation helps increase adoption, enforce best practices in using a service , and is a great way to present new functionality as it comes online. With the growing number of teams supporting public APIs, or groups needing to provide an ‘internal catalog’ to other teams, having one place for users to understand how various APIs work together is crucial. Projects like Swagger UI, Slate or Spectacle offer great documentation functionality, but focus on presenting a single API - but what if we want to provide documentation for multiple APIs cleanly through a single portal? ![]()
0 Comments
Leave a Reply. |