5-integrate swagger2

Swagger Introduce

(1) brief introduction

Swagger Is a specification and complete framework , Used to generate 、 describe 、 Invocation and visualization RESTful Style Web service (https://swagger.io/). Its main function is ：

1. It makes it more convenient to separate the front end from the back end , It's good for teamwork
2. Documentation of the interface is automatically generated online , Reduce the burden of writing interface documents for back-end developers
3. A functional test

Spring Have already put Swagger Include your own criteria , Established Spring-swagger project , Now called Springfox. By introducing Springfox , You can use it very simply and quickly Swagger.

(2)SpringBoot Integrate Swagger

• Introduce dependencies , stay zs-blog-model Introduce this dependency into the module

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
  </dependency>

Only need zs-blog-common You can configure it in , Because other microservice projects are directly or indirectly dependent .

• stay zs-blog-admin engineering config Add a configuration class to the package

package com.zs.admin.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    

   @Bean
   public Docket buildDocket() {
    
      return new Docket(DocumentationType.SWAGGER_2)
              .enable(true) // The configuration can be read for control 
              .apiInfo(buildApiInfo())
              .select()
              //  To scan API(Controller) Basic package 
              .apis(RequestHandlerSelectors.basePackage("com.zs"))
              .paths(PathSelectors.any())
              .build();
   }

   private ApiInfo buildApiInfo() {
    
      Contact contact = new Contact(" Zhang Shao's blog project ","","");
      return new ApiInfoBuilder()
              .title("zs Blog - Platform management API file ")
              .description(" Platform management services api")
              .contact(contact)
              .version("1.0.0").build();
   }
}

（3）Swagger Commonly used annotations

stay Java Class Swagger You can generate Swagger Interface document , Commonly used Swagger The comments are as follows ：

[email protected]：== Decorate the whole class , describe Controller The role of

[email protected]：== A method that describes a class , Or an interface

@ApiParam： Description information of a single parameter

@ApiModel： Use objects to receive parameters

@ApiModelProperty： use Object receives parameters when , One that describes the object Field

@ApiResponse：HTTP In response to 1 Description (s)

@ApiResponses：HTTP Respond to the overall description

@ApiIgnore： Use this annotation to ignore this API

@ApiError ： Information returned in the event of an error

@ApiImplicitParam： A request parameter

@ApiImplicitParams： Description information of multiple request parameters

@ApiImplicitParam attribute ：

attribute	Value	effect
paramType		Query parameter type
	path	Submit data as address
	query	Automatically map and assign with parameters
	body	Submit... As a stream Support only POST
	header	Parameter in request headers Submit it inside
	form	With form Form submission Support only POST
dataType		Data type of parameter As a sign only , There is no actual verification
	Long
	String
name		Receive parameter name
value		Description of the meaning of the receiving parameters
required		Whether the parameter is required
	true	Required
	false	Not required
defaultValue		The default value is

@Api(value = " Channel management ", tags = "channel", description = " Channel management API")
public interface AdChannelControllerApi {
    

    /** *  Query the channel list by name  * @param dto * @return */
    @ApiOperation(value = " Channel paging list query ", notes = " Get a one page channel list ")
    public ResponseResult findByNameAndPage(ChannelDto dto);
}

@Data
@Slf4j
public class PageRequestDto {
    

    @ApiModelProperty(value=" The current page ",required = true)
    protected Integer size;
    @ApiModelProperty(value=" Number of bars per page ",required = true)
    protected Integer page;

    public void checkParam() {
    
        if (this.page == null || this.page < 0) {
    
            setPage(1);
        }
        if (this.size == null || this.size < 0 || this.size > 100) {
    
            setSize(10);
        }
    }
}

@Api(value = " Channel management ", tags = "channel", description = " Channel management API")
public interface AdChannelControllerApi {
    

    /** *  Query the channel list by name  * @param dto * @return */
    @ApiOperation(value = " Channel paging list query ", notes = " Get a one page channel list ")
  	@ApiImplictParams({
    
      @ApiImplicitParam(name = "pageNum",value = " Page number "),
      @ApiImplicitParam(name = "pageSize", value = " The size of each page ")
    })
    public ResponseResult findByNameAndPage(Integer pageNum,Integer pageSize);
}