How to eliminate the barrier of front and rear end separation with Swagger?

This article is from the author Jiang Chao on GitChat, “Read the original” to see what questions people exchanged with the author

【 Don’t miss the Easter egg 】

Edit | auge rem

preface

With the maturity of back-end technology and the emergence of front-end framework, the separation of front-end and back-end has almost become the direction that enterprises must choose to develop.

However, when implementing the separation of the front and back ends of the project using JSP, Struts2, SpringMVC and other technologies, the use of Web container makes the front-end developers unable to focus on the display of the front end, and the separation is difficult.

The introduction of RESTful architecture makes data interaction and process control of computer terminal, mobile terminal and third-party system more convenient, and makes it possible to separate the front end from the back end.

However, as the project progresses, many apis will get bogged down in project integration if they are not managed properly. Swagger emerged to focus on providing visual documentation for apis that could be easily interfaced by front-end and back-end developers.

Front end separation is important, right?

To the project

The front-end interface focuses on the display effect, hoping to have better interaction and fast response. Background services focus on providing data and hope to have stable performance. Data security needs to be ensured to reduce system bottlenecks.

In systems with complex business logic, the most difficult to maintain is the code that is intermixed at the front and back ends. In the project team I was in, the code for searching business was originally written by JSP, with a relatively random code style. After several difficult bug fixes, it was finally abandoned.

For a company

With the front and back ends ill-defined, companies can be more difficult to recruit. Full Stack’s engineers are hard to come by, even if they are trained directly.

In addition, the full stack means that the longer the business line he controls, the greater the impact on the whole team once he leaves. Clear responsibilities and a clear division of Labour mean it is easier for companies to recruit.

For an individual

Front-end people have their own development processes, better build tools and testing methods, don’t want to build projects in Maven, don’t want to write code in Eclipse, and often need to put the user experience first.

Back end people have their own development habits. They don’t want to build with Gulp, they don’t want to debug with WebStrom, they focus on data storage and extraction, data computation, data security, and they tend to put data first.

The separation of the front and back ends is to improve efficiency, improve the development efficiency of the project, improve the recruitment efficiency of the company, and improve the learning efficiency of developers.

However, decoupled front-end and back-end development processes in the form of APIS and communicated in a RESTFul manner, project integration will be an inescapable topic. The open source project Swagger was born in this context.

Swagger preliminary cognition

Swagger project

Swagger is an umbrella term for many products. Contains the most core Specification Swagger Specification, Editor Swagger Editor, GRAPHICAL interface Swagger UI, code generator Swagger Codegen, mature product SwaggerHub and so on.

Swagger’s primary role is to describe RESTful apis and generate interactive documentation so that front-end and back-end developers can view request information and response data.

Swagger and OpenAPI

The Swagger project was originally launched by Wordnik in 2010 before it was handed over to SmartBear, a company focused on developing testing and performance tools, in 2015.

SmartBear then created an OpenAPI Initiative(OAI) under the Linux Foundation and donated Swagger.

Due to the continuous contribution of Google, IBM, Microsoft and other companies to the OpenAPI Initiative, OAI is increasingly mature, Swagger is also known as OpenAPI.

The next version of Swagger is Not Swagger 3.0, but OpenAPI 3.0

Swagger picks up quickly

To understand Swagger, you must know some of the common Swagger specifications. The official recommendation is to use JSON format or YAML syntax to write this specification. I prefer YAML, which is easier to write and read.

Swagger Editor Editor

First we need to use the Swagger Editor, you can directly use the online version, http://editor.swagger.io/, or on the local use. If node.js is already installed on your computer, use the following command to get the local editor.

Node.js is not required, you can also download the Swagger Editor source code directly

https://github.com/swagger-api/swagger-editor.

After decompressing, open./dist/index.htm L in your local browser.

Swagger Editor is an Editor that you don’t have to use to learn Swagger. You can also edit the Swagger protocol using tools like Notepad or Eclipse.

The Swagger Editor has the following advantages: 1. 2. 3. Real-time preview: write code on the left and generate UI on the right.

Swagger Specification code

Here is a “Hello World” I wrote with the Swagger specification. Using the Swagger Editor, you can quickly get the document below and see the generated graphical interface on the right.

The first is YAML format, such as swagger.yml:

If you select JSON format, such as swagger. JSON:

{" swagger ":" 2.0 ", "info" : {" version ":" 1.0.0 ", "title" : "My Hello world", "description" : "description example" }, "schemes": [ "http" ], "host": "test.com", "basePath": "/", "paths": { "/hello": { "get": { "summary": "hello, world", "description": "My first swagger.", "parameters": [ { "in": "query", "name": "name", "description": "The name of the person", "type": "string" } ], "responses": { "200": { "description": "A list of Person", } } } } }}
Copy the code

The YAML format is more comfortable to look at and easier to write. Of course, there are already a number of tools that can convert yamL-JSON to and from JSON in whatever style you like.

The content of the specification itself is easy to understand, and with the Swagger Editor it is easy to write the right API document. More detailed instructions can be found on the doc page of the official website.

Swagger UI Interactive graphical interface

The Swagger protocol you just got can be easily edited and transferred between teams, but it’s not intuitive enough, hence swagger-UI.

It is an online visualization of pure HTML, javascript, AND CSS for Swagger standards-based apis, as well as an online testing tool for the API.

You can get the source code on making https://github.com/wordnik/swagger-ui. The files in./dist/* are generated files and can be used directly, or you can modify the source code and run it using Node.

As you can see, the latest release was released on September 15, 2017. The biggest advantage of this release is that it supports OpenAPI 3.0

The file swagger-ui/dist/index.html has the following code snippet. Replace the URL in the file with your own url, such as “swagger. Yml “.

<script>
window.onload = function() {

  // Build a system
  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })
  window.ui = ui
}
</script>
Copy the code

Swagger and Spring the Boot

If your project uses Microservice and Spring Boot, building RESTful apis that can be managed manually is a nightmare. Today, Swagger’s seamless connection to Spring Boot is a boon for document-averse apes.

Required dependency

The dependency packages needed to support Swagger need to be introduced in POM.xml.


        
        
         io.springfox
         
        
         springfox-swagger2
         < version > 2.2.2 < / version > < / dependency > < the dependency > < groupId >. IO springfox < / groupId > < artifactId > springfox swagger - UI < / artifactId > < version > 2.2.2 < / version > < / dependency >
       
Copy the code

Required Configuration

To integrate Swagger into your project, you need to create a configuration class in the same directory as the launch class Application.java, with any name, such as swagger.java

@Configuration@EnableSwagger2public class Swagger { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.gitchat.controller")) .paths(PathSelectors.any()) .build(); }}
Copy the code

A basePackage() is required, otherwise all apis in the project will be documented, including Spring’s own services.

Test the

After starting the Spring Boot program, access:

http://localhost:8080/swagger-ui.html

You’ll see something like Swagger UI. Click Try It Out to test that the API is working properly.

How close is your Swagger

Whether you’re a back-end developer, a front-end developer, or a tester, you can experience Swagger’s many benefits based on the contract for the separation of the front and back ends.

Generate interactive documentation: It’s easy for developers to ignore API documentation. Programmers hate to write documentation, but complain that the program they’re maintaining doesn’t have documentation.
Human-readable vs. machine-readable: The choice of JSON and YAML as Swagger’s canonical formats is no accident. It makes it easy for more users to edit documents, share files, and easily call or convert directly between various programming languages.

Whether the Swagger specification is written manually, or the code automatically generates the Swagger specification, beautiful documentation just helps us do better development tasks. Swagger is not necessary, but may be necessary.

The front and the back are separated. Next, it’s up to you!

eggs

Blockbuster Chat

5 Learning Strategies for Learning Faster and Faster

Share:

Seaborn Lee, a programmer who writes code live at Station B, juggles balls, plays Ukulele, extreme fitness, runs, writes jokes, draws, translates, writes, speaks, trains. I like to realize my ideas with programming. I have made money in the Android market and have several start-up experiences.

Good at study, habit formation and time management. Physically influence others to make positive change! Currently, I work at ThoughtWorks, where I spread the idea of happy and productive programming. In his spare time, he founded codingstyle.cn, a software craftsman community, and organized more than 30 technical activities.

Chat profile:

When it comes to learning, it’s a big deal:

Fragmentation, no longer continuous time to learn

Hard to concentrate, holding up the book, the phone is calling: come, happy, anyway, there is plenty of time ~

Can’t do it, read a lot of books, but can’t do it in life

However, there is no use, learned methods and tools, can not find the use of the scene

Low efficiency, learning speed can not keep up with the speed of knowledge generation

Can’t remember, the speed of learning can’t keep up with the speed of forgetting

In this era of knowledge flooding and cross-border competition, learning ability is the core competitiveness. Can you think of anything you could have accomplished in the past week that didn’t require studying?

Despite its importance, most people don’t research learning, believing that by opening “get” and listening to a book on their way to and from work, they are fragmented and lifelong learners.