1 В избранное 0 Ответвления 0

OSCHINA-MIRROR/willardwang-marvin-api-doc-starter

В этом репозитории не указан файл с открытой лицензией (LICENSE). При использовании обратитесь к конкретному описанию проекта и его зависимостям в коде.
Клонировать/Скачать
Внести вклад в разработку кода
Синхронизировать код
Отмена
Подсказка: Поскольку Git не поддерживает пустые директории, создание директории приведёт к созданию пустого файла .keep.
Loading...
README.md

Springboot проект API-документ автоматический генератор

Описание фреймворка

Микросервисная интеграция

  1. Для использования необходимо импортировать зависимости в файл pom.xml:
    <dependency>
            <groupId>com.slightech.marvin.api</groupId>
            <artifactId>marvin-api-doc-starter</artifactId>
            <version>0.0.1-SNAPSHOT</version>
   </dependency>
  1. Включите конфигурацию для генерации документов:
Чтобы включить автоматическую генерацию документов в проекте, добавьте следующую конфигурацию:
marvin.api.doc.enabled = true
  1. Настройте документацию с пользовательскими описаниями:

Можно настроить глобальные словари, участников команды и описания документов.

@Configuration
public class MarvinApiDocConfig {
    @Bean
    public ApiDocInfo apiDocInfo(){
        val dictionaryDocBuilder = new DictionaryDoc
                            .DictionaryDocBuilder()
                            .name("异常错误")
                            .description("错误")
                            .tableTitleName("错误码")
                            .tableValueName("错误提示")
                            .tableDescriptionName("描述");


        for (ResultCode resultCode : ResultCode.values()) {
            val dictionary =  new Dictionary();
            dictionary.setName(resultCode.code());
            dictionary.setValue(resultCode.msg());
            dictionary.setDescription(resultCode.msg());
            dictionaryDocBuilder.addDictionary(dictionary);
        }

        val dictionaryDocOuterBuilder = new DictionaryDoc
                .DictionaryDocBuilder()
                .name("全局异常")
                .description("错误")
                .tableTitleName("错误码")
                .tableValueName("错误提示")
                .tableDescriptionName("描述");

        for (ReturnCode returnCode : ReturnCode.values()) {
            val dictionary =  new Dictionary();
            dictionary.setName(returnCode.getCode());
            dictionary.setValue(returnCode.getMsg());
            dictionary.setDescription(returnCode.getMsg());
            dictionaryDocOuterBuilder.addDictionary(dictionary);
        }

        return new ApiDocInfo.ApiDocInfoBuilder()
                .title("访客服务接口")
                .description("<p>Я являюсь интерфейсом документации для посетителей</p>")
                .addTeamMember("coder1", "coder1@slightech")
                .addTeamMember("coder2", "coder2@slightech11")
                .addDictionaryDoc(dictionaryDocOuterBuilder.build())
                .addDictionaryDoc(dictionaryDocBuilder.build())
                .build();
    }
}
  1. Запустите Springboot сервис:

Доступ к документации можно получить по адресу: http://domain:port/apiDoc.

Использование аннотаций

  • @MarvinApiDoc
  • @MarvinApi
  • @MarvinApiRequestParam
  • @MarvinApiParamField
  • @MarvinApiResponseParam
  • @MarvinApiGenericField
  • @MarvinApiParamError

1. @MarvinApiDoc

Описание:

Используется для аннотации контроллеров. Только интерфейсы с этой аннотацией будут включены в генерацию документации.

Пример:

@RequestMapping("package")
@RestController
@MarvinApiDoc(value = "套餐", order = 4)
public class CapacityPackageController extends BaseController {

}

Поля:

  • value: название группы интерфейса, которое будет отображаться в левой части документации.
  • order: порядок интерфейсов в документации слева направо, чем больше значение, тем ближе к началу.
  • description: описание группы интерфейсов.

2. @MarvinApi

Описание:

Аннотируется на методах контроллера. Используется для описания методов интерфейса и их названий на китайском языке.

Пример:

@MarvinApi(value = "初始化 комплекта", description = "Используется для инициализации комплекта на сервере", supportClientType={SupportClientType.APP, SupportClientType.WEB} )
@RequestMapping(value = "init", method = RequestMethod.POST)
 public String initBuildingPackage(@RequestParam(ApiConstant.REQUEST_JSON_PARAM_NAME)
    return buildResponseString(logger, ResultCode.SUCCESS);
}

Поля:

  • value: имя интерфейса.
  • description: описание интерфейса.
  • supportClientType: перечисление типов клиентов, которые могут вызывать интерфейс.

3. @MarvinApiRequestParam

Описание:

Аннотируются методы контроллера. Описывают параметры запроса интерфейса. Если метод использует Java Bean для преобразования параметров, то эта аннотация не требуется.

Пример:

 @MarvinApi(value = "Получить информацию о заявке")
    @MarvinApiRequestParam( field = {
            @MarvinApiParamField(name = "union_id", example = "o3iamjg7wPdNPO_uvqFM4cOr2p4w", description = "Идентификатор пользователя union_id"),
            @MarvinApiParamField(name = "apply_id", type = "int", example = "1", description = "ID заявки", required = false),
    })

``` **Поля анализа:**
* field: поле @MarvinApiParamField.

**4. @MarvinApiParamField**

Описание:
@MarvinApiParamField используется для пользовательской аннотации разбора полей, может использоваться с @MarvinApiRequestParam и @MarvinApiResponseParam для описания полей интерфейса. Также может быть использован для аннотирования автоматически преобразованных объектов JavaBean.

Пример использования с @MarvinApiRequestParam:

@MarvinApi(value = "获取申请信息") @MarvinApiRequestParam( field = { @MarvinApiParamField(name = "union_id", example = "o3iamjg7wPdNPO_uvqFM4cOr2p4w", description = "用户 union_id"), @MarvinApiParamField(name = "apply_id", type = "int", example = "1", description = "申请ID", required = false), }) @RequestMapping(value = "get_apply_join", method = RequestMethod.POST) public String getApplyJoinInfo(@RequestParam(ApiConstant.REQUEST_JSON_PARAM_NAME) Map<String, Object> params) throws IOException { return ""; }


Пример использования с @MarvinApiResponseParam:

@MarvinApi(value = "获取申请信息", description = "2222") @MarvinApiRequestParam( field = { @MarvinApiParamField(name = "union_id", example = "222", description = "用户 union_id"), @MarvinApiParamField(name = "apply_id", type = "int", example = "222", description = "申请ID", required = false), }) @MarvinApiResponseParam(field = { @MarvinApiParamField(name = "user_id", example = "1", description = "用户id"), @MarvinApiParamField(name = "apartment_id", type = "int", example = "1", description = "公寓ID", required = false), }) @RequestMapping(value = "get_apply_join", method = RequestMethod.POST) public String getApplyJoinInfo(@RequestParam(ApiConstant.REQUEST_JSON_PARAM_NAME) Map<String, Object> params) throws IOException {

    return "";
}
Пример использования для аннотирования свойств JavaBean:

@MarvinApiParamField( description = "Набор функций сервиса") private List services;


Поля анализа:
* name: имя поля;
* example: пример запроса или ответа;
* type: тип поля (int, string, boolean, file (тип файла), List<String>, List<Integer>);
* description: описание поля;
* required: требуется ли обязательное указание или обязательный возврат.

**5. @MarvinApiResponseParam**

Описание:
используется для аннотирования параметров в методе интерфейса Controller. Если интерфейс возвращает объект JavaBean, необходимо заполнить responseClass. Если это не объект JavaBean, то следует использовать описание, аналогичное @MarvinApiParamField.

Пример использования:

@MarvinApi(value = "Получение информации о заявке", description = "2222") @MarvinApiRequestParam( field = { @MarvinApiParamField(name = "union_id", example = "222", description = "Идентификатор пользователя union_id"), @MarvinApiParamField(name = "apply_id", type = "int", example = "222", description = "ID заявки", required = false), }) @MarvinApiResponseParam(field = { @MarvinApiParamField(name = "user_id", example = "1", description = "идентификатор пользователя"), @MarvinApiParamField(name = "apartment_id", type = "int", example = "1", description = "идентификатор квартиры", required = false), }) @RequestMapping(value = "get_apply_join", method = RequestMethod.POST) public String getApplyJoinInfo(@RequestParam(ApiConstant.REQUEST_JSON_PARAM_NAME) Map<String, Object> params) throws IOException {

    return "";
}
Если возвращается объект пользовательского класса, то пример использования будет выглядеть следующим образом:
@RequestMapping(value = "get_pay_list", method = RequestMethod.POST)
@MarvinApiResponseParam(responseClass = @MarvinApiResponseClass(clazz = GetPayListResponse.class))
public String getCapacityPayList(@RequestParam(ApiConstant.REQUEST_JSON_PARAM_NAME) GetCapacityPayListDTO capacityPayListDTO)
        throws IOException {

return "";

}

@MarvinApiResponseClass

В классе объекта необходимо указать класс возвращаемого объекта.

Если возвращаемый объект является универсальным классом, то пример будет выглядеть так:

public class GetPageDataListResponse { @JsonProperty("total_page") private int totalPage; @JsonProperty("total_count") private int totalCount; @JsonProperty("data") private List data; }

@MarvinApi("Получение списка пакетов услуг")
@RequestMapping(value = "admin_get_list", method = RequestMethod.POST)
@MarvinApiResponseParam(responseClass =

Комментарии ( 0 )

Вы можете оставить комментарий после Вход в систему

Введение

Инструмент для создания документации по интерфейсам Springboot. Развернуть Свернуть
Отмена

Обновления

Пока нет обновлений

Участники

все

Недавние действия

Загрузить больше
Больше нет результатов для загрузки
1
https://api.gitlife.ru/oschina-mirror/willardwang-marvin-api-doc-starter.git
git@api.gitlife.ru:oschina-mirror/willardwang-marvin-api-doc-starter.git
oschina-mirror
willardwang-marvin-api-doc-starter
willardwang-marvin-api-doc-starter
master