What are OpenAPI and Swagger?
OpenAPI is a formalized specification and a complete framework for describing, creating, using, and visualizing REST web services. The goal is to allow client systems and documentation to synchronize their updates with changes on the server. This is achieved by integrating methods, parameters, models, and other elements with the server software via OpenAPI and keeping them in sync all the time.
The specification does not depend on the programming language and can be used outside of the HTTP Protocol. OpenAPI is simultaneously applied to the client, server, and corresponding interface documentation created according to REST.
The specification can be used by clients without knowing the specifics of the server implementation. At the same time, both developers and ordinary users can work with OpenAPI using ready-made tools and provided interfaces. XML and JSON are used as the format, but in General, another markup language can be selected (for example, YAML).
OpenAPI specification
To better understand the OpenAPI specification, let’s take a look at some excerpts from the specification.
The OpenAPI elements are paths, parameters, responses and security.
In the OpenAPI specification, your endpoints are paths. The /pet the endpoint in the OpenAPI specification might look like this:
Here’s what the objects in this code mean:
/pets- path endpoint;get- HTTP method;parameters- list of input parameters for the query;responses- list of responses to the request;200- HTTP status code;$refis a reference to another part of the description where the response is defined (incomponents). The OpenAPI has many$reflinks like this to keep the code clean and make it easier to reuse it.
Swagger UI
One of the most commonly used tools for analyzing the OpenAPI specification is the Swagger UI.
Swagger was the original name of the OpenAPI specification, but the specification name was later changed to OpenAPI. Now “Swagger” refers to API tools that support the OpenAPI specification, rather than the specification itself. People still often refer to both names interchangeably, but “OpenAPI” is what the specification should be called.
In addition to the Swagger UI, other tools can analyze our OpenAPI documentation. Here are some of them:
I. Automatic generation of an OpenAPI file from code annotations
Instead of encoding the OpenAPI specification document manually, you can automatically generate it from annotations in the program code. This developer-oriented approach is most useful when there is a large number of APIs, or if it is not particularly practical to describe this documentation in advance.
Swagger offers numerous libraries that you can add to your program code to create a document in the specification. Essentially, they analyze annotations that developers add and generate a document in the OpenAPI specification. However, annotation methods differ depending on the programming language. It is important to follow the library-specific annotations rules and guidelines to generate a correct spec file.
Although this approach “automates” specification generation, you still need to understand which annotations to add and how to add them (this process is not too different from Javadoc comments and annotations).
II. Development by specification
You can generate your specification from code annotations, although there is a widespread belief that automatic generation is not the best approach. Recommend that groups manually implement the specification, and then process the specification document as a document that developers use when performing encoding. This approach is often referred to as”spec-first development”.
In other words, developers look at the specification to see what parameter names should be called, what responses should be, and so on.
The “spec-first development” approach primarily helps you use the documentation for a large team, not just for engineers. Defining the specification before implementation also helps teams create better APIs by discussing and approving the final version of the interaction interface.
Even before creating the API, the specification may generate a false response if you add response examples to the specification. The mock server generates a response that looks like it’s coming from a real server, but it’s just a predefined response in the code, and it seems dynamic to the user.
OpenSource tools for Golang
swagger-api/swagger-codegen
★ 11,6k
Swagger Codegen is a code generator for creating server and client SDK stubs from the RESTful API defined in the OpenAPI specification. It remains to make the API implementation.
The client contains methods for sending requests, and the endpoint’s server and stubs for processing them.
Examples of the folder structure can be seen below.
#swagger #function
