Документация является важным пунктом, и ключ для любого проекта программы, я обычно говорю, что документация является сердцем любого проекта, в конце концов, приложение, которое находится в неправильном оформлении документов или без каких-либо документация может затруднить понимание со стороны персонала и пользователей на поведение одного и того же. Поэтому в этой статье мы покажем мощный инструмент, который имеет целью помочь разработчикам в этом задача создания хорошей документации Api, быстро и автоматически.
Что такое SWAGGER?
Swagger-это фреймворк с открытым исходным кодом, состоящие из множества инструментов, который помогает разработчику в описании, расход и просмотра REST API,однако для выполнения таких задач Swagger использует вызов спецификации OPENAPI, которые устанавливает стандарт, стандартизированного запроса JSON. Как мы уже говорили anteriormete в swagger состоит из различных инструментов, но основными из них являются:
Редактор чванства – su funçao principalé ajudar o desenvolvedor a определить, что такое API для ума, но не инициирует производство ( https://editor.swagger.io/ )
Swagger Codegen – его основной функцией является создание, весь “скелет” API из его описание в YAML.
Swagger UI – его основной функцией является создание документации, стильный,через графический интерфейс, где пользователи могут описывать свои Api-интерфейсы, и провести испытания в тех же, без каких-либо повреждений приложение в производственной среде.
Несте артиго вамос мострар комо интегра уна апликасао ява утилизандо о чванливый пользовательский интерфейс.
Adicionando библиотека Springfox numa API com Весенняя загрузка
Com a aplicaçao criada eco mos конечные точки funcionando, adicione в pom.xml-эти две зависимости:
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
Зависимости вновь помещаются в приложение пришло время включить swagger, для этого в основной пакет приложения внутри класса Application(класс этот, который дает старт в применении и инициализирует все beans) или, если хотите, вы можете создать класс конфигурации SwaggerConfig добавьте следующий annotation @EnableSwagger2 и добавьте следующий метод установки:
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("br.com.rafael.naturassp.controller"))
.paths(PathSelectors.any())
.build();
}
}
В этом методе мы определяем, что наш бин, который мы называем Docket получите доступ ко всем конечные приложения,с этим через reflection lib уже удалось получить все конечные точки, которые доступны в приложении. Чтобы получить доступ к Swagger UI необходимо ввести( http://localhost:8080/swagger-ui.html ), результат будет выглядеть, как на рисунке ниже:
Сведения О Постройке:
Для создания специализированных необходимо создать метод, который будет возвращать объект ApiInfo как мы можем видеть в коде ниже:
private ApiInfo apiInfo() {
return new ApiInfo(
"API do curso Modern Cloud",
"Esta API é utilizada no curso do professor Isidro SpringBoot/Angular",
"Versão 1.0",
"Professor Isidro",
new Contact("Professor Isidro ", "isidro@gmail.com", ""),
"",
"",
Collections.emptyList() // Vendor Extensions
);
}
и сразу после добавления этого метода, включает следующий вызов в наш бин Docket как мы можем видеть в коде ниже:
.apiinfo (апиинфо) ())
Настройка Глобальных Сообщений:
Если вам нужно настроить все коды возврата, которые endpoint вернитесь необходимо использовать в наш бин Docket метод globalMessage получать в качестве параметра метода http и список ResponseMessage как мы можем ve ниже(в моем случае я я, задав атрибуты концу тип ResponseMessage и вызова globlaResponseMessage я положив эти атрибуты в массив)
private final ResponseMessage m201 = simpleMessage(201, "Recurso criado");
private final ResponseMessage m204put = simpleMessage(204, "Atualização ok");
private final ResponseMessage m204del = simpleMessage(204, "Deleção ok");
private final ResponseMessage m403 = simpleMessage(403, "Não autorizado");
private final ResponseMessage m404 = simpleMessage(404, "Não encontrado");
private final ResponseMessage m422 = simpleMessage(422, "Erro de validação");
private final ResponseMessage m500 = simpleMessage(500, "Erro inesperado");
private ResponseMessage simpleMessage(int code, String msg) {
return new ResponseMessageBuilder().code(code).message(msg).build();
}
globalResponseMessage(RequestMethod.GET, Arrays.asList(m403, m404, m500))
С помощью проверки Подлинности в Swagger
Casa sua aplicaçao использует альбом tipo de autenticaçao, необходимый для конфигурации, без весенней лисы, Париж, для использования в целях обеспечения безопасности и безопасности. В первом методе я устанавливаю тип аутентификации( если это ApiKey,BasichAuth,OAuth), и второй определяю особенности подлинности.
В приведенном ниже примере определим подлинности тип ApiKey в нашем bean Docket и определим, что конечная точка заказа должен иметь подлинности:
.securitySchemes(Arrays.asList(new ApiKey("Token Access", HttpHeaders.AUTHORIZATION, In.HEADER.name())))
.securityContexts(Arrays.asList(securityContext()));
private List defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope(
"global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("apiKey",
authorizationScopes));
}
private SecurityContext securityContext() {
return SecurityContext.builder().securityReferences(defaultAuth())
.forPaths(PathSelectors.ant("/pedido/**")).build();
}
После этого, поверните еще раз и снова получить доступ к экрану Swagger-UI, вы увидите в верхнем правом углу кнопку Authorize, как мы можем видеть на изображении ниже:
При нажатии на него он спросит, что вы сообщите свой маркер
После информирования свой маркер уже можно будет делать запросы в конечные, требующие проверки подлинности
Оригинал: “https://dev.to/rs_marinheiro/documente-sua-api-springboot-com-swagger-cni”