Springboot проект API-документ автоматический генератор
<dependency>
<groupId>com.slightech.marvin.api</groupId>
<artifactId>marvin-api-doc-starter</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
Чтобы включить автоматическую генерацию документов в проекте, добавьте следующую конфигурацию:
marvin.api.doc.enabled = true
Можно настроить глобальные словари, участников команды и описания документов.
@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();
}
}
Доступ к документации можно получить по адресу: http://domain:port/apiDoc.
Описание:
Используется для аннотации контроллеров. Только интерфейсы с этой аннотацией будут включены в генерацию документации.
Пример:
@RequestMapping("package")
@RestController
@MarvinApiDoc(value = "套餐", order = 4)
public class CapacityPackageController extends BaseController {
}
Поля:
Описание:
Аннотируется на методах контроллера. Используется для описания методов интерфейса и их названий на китайском языке.
Пример:
@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);
}
Поля:
Описание:
Аннотируются методы контроллера. Описывают параметры запроса интерфейса. Если метод использует 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 )