​

preface

What’s a Swagger?

Swagger Swagger is a canonical and complete framework for generating, describing, invoking, and visualizing RESTful Web services. Swagger’s goal is to define a standard, language-neutral interface to the REST API that gives people and computers the ability to discover and understand services without having to access source code, documentation, or network traffic monitoring. When properly defined with Swagger, the user can understand the remote service and interact with the remote service with minimal implementation logic. Similar to interfaces implemented for low-level programming, Swagger takes the guesswork out of calling a service.

The advantage of the Swagger

  • Support for API auto-generation of synchronized online documentation: With Swagger, you can generate documentation directly from the code instead of having to manually document your own interfaces, which is very convenient for programmers to save time on writing documentation to learn new techniques.
  • Provide Web page online testing API: Documentation isn’t enough, the documentation generated by Swagger also supports online testing. Parameters and formats are set, directly input the corresponding values of parameters on the interface can be online test interface.

The maintenance of the interface documentation has always been a time-consuming part of our development process. Each offline document update requires multiple people to confirm the update, which takes time and effort. My previous blog also built a Yapi interface maintenance platform, but today Swagger is an automated interface online document that requires no human maintenance

Create a project

We automate the creation of a Spring Boot project with IDEA

​

Introduce Swagger dependencies once the project is built (be sure to build 2.5.0 or above! Most of the blog posts cite version 2.2.2, which works fine in the demo, but you’re sure to cite other plugins during development. 2.2.2 conflicts with Feign! Bean creation loading exception is reported! :

< the dependency > < groupId > IO. Springfox < / groupId > < artifactId > springfox - swagger2 < / artifactId > < version > 2.9.2 < / version > </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> The < version > 2.9.2 < / version > < / dependency >Copy the code

Write a configuration file:

package com.ys.platform.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.bind.annotation.RestController; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; @Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket createRestApi() { List<Parameter> pars = new ArrayList<Parameter>(); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars) .apiInfo(apiInfo()); } private ApiInfo ApiInfo () {return new ApiInfoBuilder().title(" REST API").description(" Xiangyang born "). TermsOfServiceUrl (" https://blog.csdn.net/AnNanDu/article/details/105274231 "). The version (" 1.0 "). The build (); }}Copy the code

The configuration application. Yml:

server:
  port: 8181

spring:
  application:
    name: swagger
Copy the code

Write a Demo class:

package com.ys.swagger.test; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; @requestMapping ("/test") @restController @api (value = "test") public Class DemoController {@RequestMapping(value =" test") "/test") @apiOperation (value = "test",notes = "real ") public String test(){return "test"; } @requestMapping (value = "/test2") @apiOperation (value = "test2",notes =" ") public String test2(){return "test"; }}Copy the code

Start the project access address: http://127.0.0.1:8181/swagger-ui.html (IP + port/swagger – UI. HTML)

​

Click on the interface you want to see for details:

​

If you want to test the interface click Try it out and then click Execute

​

As you can see above we have the same method but there are seven request types, which is quite redundant to show on the page, so we need to define the request type when we define the interface

​

And then we’ll reboot and look at it again

​

That’s where the Swagger is built

The other parameters

@apiOperation: Describes a method of a class, or an interface. @Apiparam: describes a single parameter. @ApiModel: Uses an object to receive a parameter. @ApiResponse: Describes one of the HTTP responses. @APIResponses: Describes the entire HTTP response. @apiIgnore: Ignores the API using this annotation. Error @APIIMPLICITParAM: one request parameter @APIIMPLICITParams: multiple request parameters

​