Инструмент повышения эффективности Java swagger2

В современной организационной структуре НИОКР группа НИОКР в основном включает в себя группу продуктов, группу бэкенда, группу переднего плана, НИОКР на стороне приложения, группу тестирования, группу пользовательского интерфейса и т. д. Каждый подразделенный персонал организации выполняет свои обязанности. выполнять свои обязанности и работать вместе, чтобы завершить полный цикл продукта. Как осуществлять эффективную и действенную коммуникацию внутри организационной структуры особенно важно. Среди них важнее то, как создать разумный и эффективный интерфейсный документ.

Документация по интерфейсу проходит через сотрудников отдела исследований и разработок на всех концах, но из-за многочисленных интерфейсов и различных деталей иногда ее нелегко понять, что приводит к неизбежности «гражданской войны», а обслуживание также является большой проблемой.

Как и в системе управления документами RAP, документы интерфейса поддерживаются в режиме онлайн, что удобно для просмотра и разработки стыковки персоналом внешнего интерфейса и приложения, но все же есть следующие проблемы:

• Документ вручную импортируется поставщиком интерфейса, это статический документ, и функция тестирования интерфейса не предусмотрена;
  
• Уход не сложный.
  

Появление Swagger может прекрасно решить вышеуказанные болевые точки традиционных методов управления интерфейсом. В этой статье представлен процесс интеграции Swagger2 в Spring Boot вместе с заполнением ямы.

Процесс использования выглядит следующим образом:

1) Введите соответствующий пакет maven:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>

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

2) Напишите класс конфигурации для Swagger2:

package com.trace.configuration;

import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* Created by Trace on 2018-05-16.<br/>
* Desc: swagger2配置类
*/
@SuppressWarnings({"unused"})
@Configuration @EnableSwagger2
public class Swagger2Config {
   @Value("${swagger2.enable}") private boolean enable;

   @Bean("UserApis")
   public Docket userApis() {
       return new Docket(DocumentationType.SWAGGER_2)
           .groupName("用户模块")
           .select()
           .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
           .paths(PathSelectors.regex("/user.*"))
           .build()
           .apiInfo(apiInfo())
           .enable(enable);
   }

   @Bean("CustomApis")
   public Docket customApis() {
       return new Docket(DocumentationType.SWAGGER_2)
           .groupName("客户模块")
           .select()
           .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
           .paths(PathSelectors.regex("/custom.*"))
           .build()
           .apiInfo(apiInfo())
           .enable(enable);
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
           .title("XXXXX系统平台接口文档")
           .description("提供子模块1/子模块2/子模块3的文档, 更多请关注公众号: 随行享阅")
           .termsOfServiceUrl("https://xingtian.github.io/trace.github.io/")
           .version("1.0")
           .build();
   }
}

Как видно выше:

• Включите swagger2, аннотировав @EnableSwagger2, apiInfo — это основная информация описания документа интерфейса, включая заголовок, описание, URL-адрес службы, контактное лицо, версию и другую информацию;
  
• При создании Docket группировка выполняется по groupName, свойство paths фильтруется, а свойство apis может задавать пакет сканирования или идентифицировать его по аннотации; через свойство enable можно установить соответствующее значение в application-{profile} Файл .properties, в основном используемый Документация по интерфейсу не создается для контрольной производственной среды.

3) Добавьте связанные аннотации к классам и методам уровня контроллера.

package com.trace.controller;

import com.trace.bind.ResultModel;
import com.trace.entity.po.Area;
import com.trace.entity.po.User;
import com.trace.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.List;

/**
 * Created by Trace on 2017-12-01.<br/>
 * Desc: 用户管理controller
 */
@SuppressWarnings("unused")
@RestController @RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
    @Resource private UserService userService;

    @GetMapping("/query/{id}")
    @ApiOperation("通过ID查询")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path")
    public ResultModel<User> findById(@PathVariable int id) {
        User user = userService.findById(id);
        return ResultModel.success("id查询成功", user);
    }


    @GetMapping("/query/ids")
    @ApiOperation("通过ID列表查询")
    public ResultModel<List<User>> findByIdIn(int[] ids) {
        List<User> users = userService.findByIdIn(ids);
        return ResultModel.success("in查询成功", users);
    }


    @GetMapping("/query/user")
    @ApiOperation("通过用户实体查询")
    public ResultModel<List<User>> findByUser(User user) {
        List<User> users = userService.findByUser(user);
        return ResultModel.success("通过实体查询成功", users);
    }


    @GetMapping("/query/all")
    @ApiOperation("查询所有用户")
    public ResultModel<List<User>> findAll() {
        List<User> users = userService.findAll();
        return ResultModel.success("全体查找成功", users);
    }


    @GetMapping("/query/username")
    @ApiOperation("通过用户名称模糊查询")
    @ApiImplicitParam(name = "userName", value = "用户名称")
    public ResultModel<List<User>> findByUserName(String userName) {
        List<User> users = userService.findByUserName(userName);
        return ResultModel.success(users);
    }


    @PostMapping("/insert")
    @ApiOperation("新增默认用户")
    public ResultModel<Integer> insert() {
        User user = new User();
        user.setUserName("zhongshiwen");
        user.setNickName("zsw");
        user.setRealName("钟仕文");
        user.setPassword("zsw123456");
        user.setGender("男");
        Area area = new Area();
        area.setLevel((byte) 5);
        user.setArea(area);
        userService.save(user);
        return ResultModel.success("新增用户成功", user.getId());
    }


    @PutMapping("/update")
    @ApiOperation("更新用户信息")
    public ResultModel<Integer> update(User user) {
        int row = userService.update(user);
        return ResultModel.success(row);
    }


    @PutMapping("/update/status")
    @ApiOperation("更新单个用户状态")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true),
            @ApiImplicitParam(name = "status", value = "状态", required = true)
    })
    public ResultModel<User> updateStatus(int id, byte status) {
        User user = userService.updateStatus(id, status);
        return ResultModel.success(user);
    }


    @DeleteMapping("/delete")
    @ApiOperation("删除单个用户")
    @ApiImplicitParam(value = "用户ID", required = true)
    public ResultModel<Integer> delete(int id) {
        return ResultModel.success(userService.delete(id));
    }
}

4) Вернуть объект ResultModel

package com.trace.bind;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;

/**
* Created by Trace on 2017-12-01.<br/>
* Desc:  接口返回结果对象
*/
@SuppressWarnings("unused")
@Getter @Setter @ApiModel(description = "返回结果")
public final class ResultModel<T> {
    @ApiModelProperty("是否成功: true or false")
    private boolean result;
    @ApiModelProperty("描述性原因")
    private String message;
    @ApiModelProperty("业务数据")
    private T data;

    private ResultModel(boolean result, String message, T data) {
        this.result = result;
        this.message = message;
        this.data = data;
    }

    public static<T> ResultModel<T> success(T data) {
        return new ResultModel<>(true, "SUCCESS", data);
    }


    public static<T> ResultModel<T> success(String message, T data) {
        return new ResultModel<>(true, message, data);
    }


    public static ResultModel failure() {
        return new ResultModel<>(false, "FAILURE", null);
    }


    public static ResultModel failure(String message) {
        return new ResultModel<>(false, message, null);
    }
}

5) Объект свойства ApiModel - Пользовательский объект

package com.trace.entity.po;

import com.trace.mapper.base.NotPersistent;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;

/**
 * Created by Trace on 2017-12-01.<br/>
 * Desc: 用户表tb_user
 */
@SuppressWarnings("unused")
@Data @NoArgsConstructor @AllArgsConstructor
@ApiModel
public class User {
    @ApiModelProperty("用户ID") private Integer id;
    @ApiModelProperty("账户名") private String userName;
    @ApiModelProperty("用户昵称") private String nickName;
    @ApiModelProperty("真实姓名") private String realName;
    @ApiModelProperty("身份证号码") private String identityCard;
    @ApiModelProperty("性别") private String gender;
    @ApiModelProperty("出生日期") private LocalDate birth;
    @ApiModelProperty("手机号码") private String phone;
    @ApiModelProperty("邮箱") private String email;
    @ApiModelProperty("密码") private String password;
    @ApiModelProperty("用户头像地址") private String logo;
    @ApiModelProperty("账户状态 0:正常; 1:冻结; 2:注销") private Byte status;
    @ApiModelProperty("个性签名") private String summary;
    @ApiModelProperty("用户所在区域码") private String areaCode;
    @ApiModelProperty("注册时间") private LocalDateTime registerTime;
    @ApiModelProperty("最近登录时间") private LocalDateTime lastLoginTime;

    @NotPersistent @ApiModelProperty(hidden = true)
    private transient Area area; //用户所在地区

    @NotPersistent @ApiModelProperty(hidden = true)
    private transient List<Role> roles; //用户角色列表
}

Кратко расскажу о нескольких важных аннотациях Swagger2:

@Api: используется в запрошенном классе для указания описания класса.

• теги "Опишите роль этого класса, аннотации, которые можно увидеть в интерфейсе пользовательского интерфейса"
  
• value "Этот параметр не имеет смысла, он также отображается в пользовательском интерфейсе, поэтому настройка не требуется"
  

@ApiOperation: используется в запрошенном методе, объясняя цель и функцию метода.

• value="Опишите цель и функцию метода"
  
• notes="Примечания к методу"
  

@ApiImplicitParams: используется в запрошенном методе, указывая набор описаний параметров.

@ApiImplicitParam: используется в аннотации @ApiImplicitParams для указания различных аспектов параметра запроса.

• value: описание китайских иероглифов и объяснение параметра
  
• обязательный: должен ли быть передан параметр
  
• paramType: где находится параметр
  

1. Заголовок --> Получить параметры запроса: @RequestHeader
2. запрос --> Получить параметры запроса: @RequestParam
3. путь (для спокойного интерфейса) --> получение параметра запроса: @PathVariable
4. тело (обычно не используется)
5. форма (не часто используется)

• dataType: тип параметра, строка по умолчанию, другие значения dataType="Integer"
  
• defaultValue: значение параметра по умолчанию
  

@ApiResponses: используется в методе запроса, представляющем набор ответов.

@ApiResponse: используется в @ApiResponses, обычно используется для выражения неверного ответного сообщения.

• код: число, например 400
  
• сообщение: информация, например "параметры запроса не заполнены"
  
• ответ: класс, который выдает исключение
  

@ApiModel: есть два основных варианта использования:

• Используется в классе ответа, представляющем сообщение, которое возвращает данные ответа.
  
• Ввод параметра: используйте такие сценарии, как @RequestBody, Когда параметры запроса нельзя описать с помощью аннотации @ApiImplicitParam
  

@ApiModelProperty: используется в свойствах для описания свойств класса ответа.

Окончательный результат рендеринга:

Как уже упоминалось: импортированный swagger-ui через maven:

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

Затем, после запуска приложения, будет автоматически сгенерирована страница http://{root-path}/swagger-ui.html.После доступа эффект следующий:

Вы можете протестировать интерфейс онлайн, например интерфейс, запрашиваемый по идентификатору /user/query/{id}.

Полный текст закончился!

Следующий:Ломбок инструментов повышения эффективности Java