Tecnología Java-Documentación de la interfaz-Swagger2 y Swagger3 y documentación de la interfaz Integración de la interfaz de usuario

Swagger es una herramienta de generación de documentos para definir especificaciones estándar unificadas en interfaces (api) en empresas. Es conveniente para la pereza de los grandes amigos de back-end, pero escribir anotaciones también es problemático, pero si la iteración de la versión es rápida o la movilidad del personal es grande, causará muchos problemas. Por lo tanto, muchas empresas tendrán documentos de especificación unificados para definir estándares de interfaz.

1. Uso completo de Swagger2

1. Dependencia de POM

<propiedades>
<springfox-swagger.versión>2.9.2</springfox-swagger.versión>
</propiedades>

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${springfox-swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${springfox-swagger.version}</version>
            </dependency>

2. Clase de interfaz

Ver [3.2]

3. Clase de implementación

Ver [3.3]

4. Alojamiento de recursos estáticos

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@EnableSwagger2
@EnableWebMvc
@Configuration
public class ApiDocConfiguration extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

        super.addResourceHandlers(registry);

    }

}

5. Configuración del documento de la interfaz

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;

@Configuration
public class SwaggerConf {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ikong.service.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("开放接口平台")
                .description("")
                .contact(new Contact("ikong", "http://ikong.ik.com", "[email protected]"))
                .version("1.0")
                .build();
    }
}

6. El entorno de producción cierra el documento de interfaz.

Ver [3.6]

7. Efecto de página Swagger3

Método de implementación de paquetes múltiples de Swagger2

2. Uso completo de Swagger3

1. Dependencia de POM

2. Clase de interfaz

3. Clase de implementación

4. Alojamiento de recursos estáticos

5. Configuración del documento de la interfaz

6. El entorno de producción cierra el documento de interfaz.

7. Efecto de página Swagger3

3. Swagger integra Knife4jUi

1. Dependencia de POM

<propiedades>
<knife4j-swagger.versión>3.0.3</knife4j-swagger.versión>
</propiedades>

<dependencia> 
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>knife4j-spring-boot-starter</artifactId> 
    <version>${knife4j-swagger.version}</version> 
</dependency>

2. Clase de interfaz

import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

public interface TestApi {

    String test1(@RequestParam(value = "name") String name);

    TestRet test2(@RequestBody TestReq req);

    Result<TestRet> test3(@RequestBody TestReq req);
}

3. Clase de implementación


import com.ikong.api.TestApi;
import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import com.jd.security.framework.common.model.ResultUtils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@Api(tags = "验证参数类型")
@RestController
@RequestMapping("/test")
public class TestApiController implements TestApi {

    @ApiOperation("001接收普通参数")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @GetMapping("test1")
    @Override
    public String test1(@RequestParam(value = "name") String name) {
        return "hello," + name;
    }

    @ApiOperation("002接收对象参数")
    @GetMapping("test2")
    @Override
    public TestRet test2(TestReq req) {
        return new TestRet(Long.valueOf(req.getId()), 200);
    }

    @ApiOperation("003返回标准格式")
    @PostMapping("test3")
    @Override
    public Result<TestRet> test3(@RequestBody TestReq req) {
        return ResultUtils.wrapSuccess(new TestRet(Long.valueOf(req.getId()), 200));
    }
}

4. Alojamiento de recursos estáticos


import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class ApiDocHandlerConfiguration extends WebMvcConfigurationSupport {

    @Value("${swagger.enable:true}")
    private Boolean enable = false;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        if (enable) {
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
}

5. Configuración del documento de la interfaz


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
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.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2WebMvc
public class ApiDocKnife4jUiConfig {
    @Bean
    public Docket docket(Environment environment) {
        // 添加接口请求头参数配置 没有的话 可以忽略
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token")
                .description("令牌")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)//是否启动swagger 默认启动
                .groupName("ikong")//所在分组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ikong.service.impl"))//指定扫描的包路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        Contact author = new Contact("ikong", "api.ik.com", "[email protected]");
        return new ApiInfo(
                "开放平台接口文档",
                "开放平台接口文档",
                "1.0",
                "",
                author,
                "",
                "",
                new ArrayList<>()
        );

    }
}

6. El entorno de producción cierra el documento de interfaz.

aplicación.propiedades

swagger.habilitar=falso

7. Efecto de página Knife4jUi

URL: http://localhost:8083/doc.html

4. Explicación de notas y parámetros

Descripción del parámetro:
nombre --
valor del nombre del parámetro -- descripción del parámetro
requerida -- si se debe completar
dataType -- tipo de datos
paramType --
ejemplo de tipo de parámetro -- ejemplos de
anotaciones comúnmente utilizadas:

@Api() para clases;

Representa el recurso que identifica esta clase como swagger

@ApiOperation() para métodos;

Representa el funcionamiento de una solicitud http.

@ApiParam() se utiliza para la descripción de métodos, parámetros y campos;

Indica la adición de metadatos al parámetro (descripción o si es obligatorio, etc.)

@ApiModel() para clases

Indica la descripción de la clase, utilizada para recibir parámetros con clases de entidad.

@ApiModelProperty() para métodos, campos

Indica una descripción del atributo del modelo o un cambio en la operación de datos

@ApiIgnore() para clases, métodos, parámetros de métodos

Indica que este método o clase se ignora

@ApiImplicitParam() para métodos

Indica parámetros de solicitud individuales

@ApiImplicitParams() para métodos que contienen varios @ApiImplicitParams

Instrucciones específicas de uso:

1.@Api()

  ···
  @Api("测试用例1")
  @Controller
  public class swaggerTestUse(){
  }

2.@OperaciónApi()

···
@Api("测试用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
    public void apiOperationSwaggerTest(){
    }
}

3. @ApiParam()

···
@Api("测试用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
    public void apiOperationSwaggerTest(@ApiParam(name = "id", value = "id入参", required = true) Integer id){
    }
}

4.@ApiModel()

···
@ApiModel(description = "测试实体类", value = "测试实体类")
public class Album implements Serializable {
    ···
}

5.@PropiedadModeloApi()

···
@ApiModel(description = "测试实体类", value = "测试实体类")
public class User implements Serializable {
    @ApiModelProperty(name = "userName", value = "用户名", required = false, exmaple = "小明")
    private String userName;
}

6. @ApiImplicitParams() y @ApiImplicitParam()

    ···
  @Api("测试用例1")
  @Controller
  public class swaggerTestUse(){
      @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
      @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入参", required = true, dataType = "Integer", paramType = "query"),
                        @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
    })
      public void apiOperationSwaggerTest(Integer id, Brand band){
      }
  }