Server Framework Guides
Here, you’ll find a comprehensive collection of step-by-step guides for generating OpenAPI specs for popular server frameworks in various languages. Or read our guide below for advice on how to generate an OpenAPI schema from your existing code base.
TypeScript Frameworks
Python Frameworks
Go Frameworks
Java Frameworks
PHP Frameworks
Ruby Frameworks
How to generate an OpenAPI schema from your code
An OpenAPI schema (also called an OpenAPI specification) is a text description of your web service in detail. Your customers and automated tools can use this document to interact with your service with the confidence that they know exactly what each operation does and how to use it.
Some companies start designing their software service in an OpenAPI schema and use that schema to generate their server code. This is called the schema-first approach.
But it’s more likely you started building software to service a market, then realized the benefits of providing OpenAPI tools to your clients, and now want to know how to create and maintain an OpenAPI schema from your existing server code. This is the code-first approach. This guide will explain how to generate a schema from code, and link to all the necessary tools in the programming language you use.
But first, let’s summarize the benefits of using OpenAPI and the variations of the code-first approach that you can choose from.
The benefits of OpenAPI
If you don’t have an OpenAPI schema, you still need to write documentation, with examples, explaining to your clients how they can call your API. You also need to update this documentation whenever the code changes on your server.
Writing this documentation in the standard OpenAPI format provides the following benefits:
- Enables your clients to browse the schema in their tool of choice, such as Swagger UI , with good usability.
- Allows the schema to be used for automatic SDK generation, enabling your clients to call your server directly from code without needing to handle REST web calls or use curl. Even if you don’t generate an SDK, using an OpenAPI schema to validate the code that clients use to call your service can reduce confusion and errors.
- Supports the generation of server code stubs with statically typed request parameters and responses that you can use to validate that your server code matches the schema.
Different workflows to support OpenAPI
If you take a code-first approach, you can either annotate your existing code with special comments that an automated tool uses to generate an OpenAPI schema, or start coding in a meta-framework that generates both the server code and the OpenAPI schema. (We call it a meta-framework because it sits above both your code and your schema, controlling both.)
There are two types of annotation:
- Text comments, which are not part of the programming language in which your server is written.
- Attributes, which are valid code in the programming language.
Attributes are superior, as the compiler and your IDE can check that your annotations are syntactically valid code as you work. Attributes can also be refactored, unlike comments.
The danger of using annotations is human error. Programmers need to update annotations correctly whenever they change an operation, but they may forget to or make mistakes. Even when attribute annotations are syntactically correct, they may still describe the operation incorrectly. This will cause your code and schema to drift apart, potentially causing errors when clients try to call your API.
Using a meta-framework, on the other hand, automatically synchronizes your code and schema but requires writing code in the new framework, adding a compilation step, and learning a new tool.
A third option that falls between annotations and meta-frameworks is to use an OpenAPI-aware web framework. These frameworks are designed with native support for OpenAPI features and can automatically generate an OpenAPI schema from the code you write, usually with more detail than that provided in annotations. OpenAPI-aware frameworks, however, tend to be very new, and the most popular (and older) frameworks, like Django and Laravel, are not OpenAPI-aware.
Note that the workflow options we discuss here depend on the availability of tools to support them in your programming language. Popular web languages will have tools for a range of options, but obscure languages may not. You will also find it easier to use a statically typed language, like Go, than a dynamic one, like PHP.
The following process will probably work best for most companies wanting to support OpenAPI:
- Generate an OpenAPI schema for your code, as we describe in the rest of this article.
- Use the new schema as your principal source from now on and generate server code from the schema rather than the other way around. (There is a section explaining schema-first workflows at the end of this guide.)
- Generate SDKs from the schema to make it simple for your clients to call your API.
If you want to keep your code as the principal source, you may want to include an automated reminder in your version-control process to tell programmers to update annotations whenever they commit code.
Four techniques to extract an OpenAPI schema
The next four sections will show you different ways to generate an OpenAPI schema document from your existing code by:
- Recording network traffic
- Adding comment annotations
- Adding attribute annotations and changing your code to use an OpenAPI-aware framework
- Rewriting your code using a meta-framework
Each technique varies depending on the programming language. This guide provides examples in Go, as it’s a popular, statically typed language specifically designed for web services.
The first thing to check is whether your web server framework already natively supports OpenAPI. If it does, you can stop reading this article and follow the framework documentation on how to access the schema the framework automatically creates. If not, read on to discover your options.
If you don’t have an API yet but want to learn about OpenAPI for future projects, choose a server framework and language with native OpenAPI support. Alternatively, start by documenting your proposed API as a schema using a Swagger tool, then use a framework that supports code generation from the schema.
Use HAR and APIGit to generate a schema
The first way to create a schema is to use a tool that listens to your network calls and extracts the schema automatically from the HTTP calls it sees. Generating a schema from network traffic does not depend on programming language. The process is the same for all languages.
The benefit of this approach is that you don’t have to manually read your code and document (potentially with mistakes) what the calling contract should be. Instead, the network tool will tell you what actual data is sent, allowing you to spot any unintended parameters when reading through the schema after creation.
The disadvantage is that you have to manually call every operation in your API with all possible parameters to ensure the generator records all variations and creates an accurate schema.
For smaller APIs, you might prefer manually adding annotations or writing code to generate a schema. But for any other project, we recommend using this network listener approach, even in conjunction with other approaches, as it provides an automated review of your existing API.
HAR example
Let’s use the standard Pet Store OpenAPI example to demonstrate how to use a network listener.
- Browse to https://petstore31.swagger.io/#/pet/addPet in a Chromium-based browser.
- Open the developer tools (F12) and select the Network tab.
- Select only Fetch/XHR.
- Click Execute in the web page to start a network call to the API to add a pet.
- In the developer tools, click the
petline that appears to see the details of the request and response.