We can go beyond generating API documentation of OpenAPI schemas, but to successfully utilize innovative solutions, you have to follow the path of the API Product lifecycle.
Early days of APIs
In 2008, REST APIs were rough and based on XML. They seemed simple to implement, but they weren't implemented well, partially because we didn’t have standards well adapted.
Having a schema in Web Application Description Language (WADL) you were able to auto-generate documentation. It was like a standard of how to design REST APIs in XML. WADL didn’t get popular, because using XML was inconvenient.
JSON pushed XML APIs off the scene, and Swagger brought the standard definitions: a schema. Now you can auto-generate RESTful API documentation from a swagger/OpenAPI specification file.
REST APIs became easier to build, fairly consistent, and aggregator tools make it possible to connect APIs.
API Product lifecycle
The failure of Product management, in general, is the philosophy of “If you build it, they will come…”
API Product cycle (CI/CD tech stack): automation to generate good content and make it easier to provide updates to the APIs, API documentation, API libraries, SDKs on the developer portal. To get even the smallest updates automatically reflected, you first have to create a solid design: start with the OpenAPI schema and build from there.
Identify the problem
Determine value points and use cases
Understand your customers: what problems does the developer community have? What are your partners trying to build?
Research to understand the problem
Establish high-level architecture
Come up with the right solutions for your partners: How to make it as easy as possible to build what they want?
What can be the solution? Schema.org, GraphQL, or REST?
Create a schema definition for the API
Use IDEs to write and validate your OpenAPI schema
Implement -- if and after you have the OpenAPI schema
Build the API
want to accommodate OpenAPIs more
know how to set up the proxy-structure, what are the end-points or errors are going to be -- the gateway can handle some of the errors
Schema + Gateway = make it easier to build and launch the API
Launch the API and have an elegant Developer experience
Nicely looking, well-designed Documentation
Mock servers to let developers interact with APIs using test data
Maintain & Iterate
Manage the developer community
Developer Relationship Management
What comes next to make APIs better
obvious iterations and opportunities
Auto-generate end-points from the models of the OpenAPI schema
Visually planning OpenAPI schema: using mapping-tools to visualize how your API should work
Developer portal solutions beyond documentation: automate the management of your App marketplace
Create a mapping between the OpenAPI and your database schema, and generate server-side codes that make queries to your database
Better monitoring and logging tools integrating with customer service solutions to improve customer and developer experience
Developer Relationship Management (DRM) as a business
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.