Внешние интерфейсные документы всегда были относительно примитивными, и в основном передаваемые документы передаются. Недавно я обнаружил новую игрушку, которая может сэкономить много проблем на интерфейсе.
Swagger - это удобная структура документации API. Он может отображать тип интерфейса для другого разработчика наиболее полным образом, избегая одностороннего и ошибочного поведения рукописных документов.
В настоящее время есть два типа Swagger и Swagger2. 1 более хлопотно, поэтому вы не рассматриваете его использовать. Эта статья в основном записывает два способа использования Swagger2 в качестве внешнего интерфейса. Пожалуйста, проверьте это позже.
1. Используйте традиционный Springmvc для интеграции Swagger2
1. Зависимость Maven
<!-Springfox зависимости-> <Dependency> <groupId> com.fasterxml.jackson.core </GroupId> <ratifactId> jackson-core </artifactid> <sersive> 2.8.0 </version> </artifactiD> <pergificid> com.fasterxml.chore.core </artifactId> <sersion> 2.6.3 </version> </dependency> <Dependency> <groupId> com.fasterxml.jackson.core </GroupId> <ArtifactId> jackson-annotations </artifactid> <serse> 2.6.3 </version> </artifactiD> <dehyed> <groupid> spnifactguge> <stratifactid> <StraMifageD> <sersion> 2.4.0 </version> </getyederiny> <lepegulcy> <groupid> io.springfox </groupid> <artifactid> springfox-swager-ui </artifactid> <serse> 2.4.0 </version> </depervice>
2. Добавьте конфигурацию статического отображения в Spring-Mvc.xml (на самом деле, я могу удалить это в своем проекте, я не знаю, в чем заключается ситуация):
<!-Swagger Static Pail Path-> <MVC: Resources Location = "classPath:/meta-inf/resources/" mapting = "swagger-ui.html"/> <mvc: resources location = "classpath:/meta-inf/resources/webjars/" mapping = "/webjars/**"/>
Примечание: я не буду публиковать базовую конфигурацию SpringMVC. Следует отметить, что если вы видите, что вы видите, что выходит интерфейс Swagger-ui.html, но он пуст, пожалуйста, проверьте конфигурацию перехватчика в вашем web.xml. Сначала вы должны перехватить Springmvc, а затем отобразится интерфейс.
3. Тогда есть класс конфигурации Swagger2:
@Configuration @entableswger2public class swaggerconfig extends webmvcconfigurationsupport {@bean public docket createrestapi () {return new Docket (documentType.swager_2) .apiinfo (apiinfo ()) .select () .apis (requestHandlerselectors.basepackage ("net.laoyeyey.yyblog")) .paths (pathselectors.any ()) .build (); } private apiinfo apiinfo () {return new apiinfobuilder () .title ("yyblog project apis restful") .description ("yyblog project api документация") .version ("1.0") .build (); }}ПРИМЕЧАНИЕ. Если пути могут быть скорректированы на PathSelectors.none () в производстве, он не отображает всю информацию о интерфейсе;
4. Конфигурация информации о интерфейсе
То есть настроить соответствующую информацию о интерфейсе в контроллере SpringMVC
@Controller@requestMapping (value = "aitou")@api (description = "Информационный запрос на службу Service-Service-Account") Public Class DailyOperationDataController {logger logger = logger.getLogger (DailyOperationDataController.class); @Autowired Private DailyOperationDataService DailyOperationDataService; / * * @Apioperation (value = "interface description", httpmethod = "Метод запроса интерфейса", ответ = "Тип параметра возврата интерфейса", notes = "Notes Replace Notes" * @apiparam (обязательный = " - это параметр, необходимый", name = "Имя параметра", значения = "Специфическое описание" */ @ApiOper = {RequestMethod.post, requestMethod.get}, value = "/Query/DailyData/{dataDate}") @Responsebody public DailyOperationDatadto getDailyReportByDataDate (@pathvariable ("dataDate") String DataDate) {try eaveryOperation.getAdaLeport; (Exception e) {logger.error (e.getMessage (), e);Примечание: обычно Swagger2 отображает все интерфейсы под пакетом сканирования. Здесь я являюсь внешним интерфейсом, чтобы быть отдельным пакетом, чтобы избежать отображения слишком большого количества интерфейсов. Конечно, метод интерфейса также может предотвратить его отображение. Вы можете увидеть соответствующие аннотации ниже.
Некоторые часто используемые примечания
@API: используется в классе, чтобы проиллюстрировать функцию класса
@Apioperation: используется в методах, чтобы проиллюстрировать функцию методов
@ApiimplicitAparams: используется для включения набора описаний параметров в метод
@Apiimplicitparam: используется в аннотации @apiimplicitarparams, укажите различные аспекты параметра запроса Paramtype: где разместить параметр ・ заголовок -> Получить параметр запроса: @requestheader
・ Запрос -> Получение параметров запроса: @RequestParam
・ PATH (для RESTFUL Interface) -> Получить параметры запроса: @PathVariable
・ Тело (обычно не используется)
・ Форма (обычно не используется)
Имя: Имя параметра DataType: Требуется тип параметра: должен ли параметр быть передано значение: параметр Значение DefaultValue: параметр значения по умолчанию
@Apiresponses: используется для представления набора ответов
@Apiresponse: используется в @Apiresponses, он обычно используется для выражения кода ответа на ошибку: число, например, 400
Сообщение: сообщение, например, «Параметр запроса не заполнен»
Ответ: класс, который бросает исключение
@Apiparam: Описание однократного параметра
@Apimodel: Опишите информацию модели и использует объекты для получения параметров (это обычно используется при создании постов, используя сценарии @requestbody, и при запросе параметров не может быть описано с использованием аннотации @apiimplicitaram))
@Apimodelproperty: Опишите свойства модели
@ApipRoperty: при использовании объекта для получения параметров опишите поле объекта
@Apiignore: используйте эту аннотацию, чтобы игнорировать этот API
По сути, это все вышеперечисленное. Разве это не очень легко? Посмотрим изображение эффекта ниже
2. Используйте Springboot для интеграции Swagger2
Вышеупомянутое с использованием традиционного Springmvc для интеграции Swagger2. Давайте поговорим о недавнем популярном методе Springboot. На самом деле, принципы одинаковы.
1. Зависимость Maven
<!-Springfox зависимость-> <Dependency> <groupFox> io.springfox </GroupId> <straCatid> Springfox-swagger2 </artifactid> <seriate> 2.7.0 </version> </repertive> <dependency> <groupid> io.springfox </artifactid> springfox-s-swager-U. <версия> 2.7.0 </version> </depertion>
Это внутреннее использование моего личного проекта, который я недавно написал, используя Springboot, и в версии используется версия 2.7.0.
2. Добавить конфигурацию статического ресурса
@Configurationpublic class webmvcconfig extends webmvcconfigureradapter {/ ** * Настройка пути статического ресурса и пути для загрузки файла * * @param реестр */ @@override public void addresourcehandlers (ресурсхандлеррегистрация) { Registry.addresourcehandler ("/static/**"). Addresourcelocations ("classpath:/static/"); Registry.addresourcehandler ("/upload/**"). Addresourcelocations (Environment.getProperty ("Spring.Resources.static-Locations")); /*swagger-ui*/registry.addresourcehandler ("swagger-ui.html"). addresourcelocations ("classpath:/meta-Inf/resources/"); Registry.addresourcehandler ("/webjars/**"). addresourcelocations ("classpath:/meta-insf/resources/webjars/"); }}На самом деле, это только последние два предложения. Если вы не настроите это, вы увидите ошибку 500 или 404, когда посетите Swagger-UI.HTML. Если вы не можете вспомнить это, это должно быть 404.
3. Класс конфигурации Swagger2
Как и выше, в основном нет разницы
@Configuration@enableSwger2@enableWebMVCPublic Class SwaggerConfig Extends webmvcconfigurationsupport {@bean public docket createrestapi () {return new Docket (documentType.swagger_2) .apiinfo (apiinfo () .select () .APIS (requestHandlerselectors.basepackage ("net.laoyeye.yyblog.web.frontend")) .paths (pathselectors.none ()) .build (); } private apiinfo apiinfo () {return new apiinfobuilder () .title ("yyblog project apis restful") .description ("yyblog project api document") .version ("1.0") .build (); }}Обратите внимание, что у меня есть проблема с пути выше. Копия напрямую не отображает API (#^.^#)
4. Конфигурация интерфейса
/*** Контроллер статьи на стойке регистрации* @Author Grandpa в магазине круглосуточного магазина* @Date 5 мая 2018 г.* @Website www.laoyeye.net*/ @api (description = "Query Query") @Controller @requestmapping ("/article") публичный класс Articlecontroller {@autowired Private Articleservice articleservice; @Autowired private settingservice serviceservice; @Autowired частный Cateservice Cateservice; @Autowired Private Tagreferservice Tagreferservice; @Autowired private userservice userservice; @Autowired Private ArticleMapper ArticleMapper; @Autowired Private Commentservice Commentservice; @Apioperation (value = "Query Interface") @apiimplicitparam (name = "id", value = "id статья", обязательный = true, dataType = "long") @getmaping ("/{id}") public String index (модель модели, @pathvaraible ("id") long id) {trest {articles ytularers.updateviable ("id") {try {try {trest {trest {articlessevice. } catch (исключение игнорировать) {} list <Tust> futings = sturnService.listall (); Map <string, object> map = new hashmap <string, object> (); для (настройка настройки: настройки) {map.put (stence.getCode (), setting.getValue ()); } Статья статьи = articleservice.getarticlebyid (id); model.addattribute («Настройки», карта); model.addattribute ("catelist", categoryservice.listallcate ()); model.addattribute («статья», статья); model.addattribute ("Tags", tagreferservice.listnamebyarticleid (article.getid ())); model.addattribute ("Автор", userservice.getnicknamebyid (article.getauthorid ())); // Изменение model.addattribute («Статьи», articlemapper.listarticlebytitle (null)); model.addattribute («аналогичные», articlemapper.listarticlebytitle (null)); Комментарий Query = new CommentQuery (); Query.setLimit (10); Query.SetPage (1); Query.setarticleId (id); model.addattribute («Комментарии», комментарии. вернуть "frontend/article"; } @Apioperation (value = "articlecomment Query Interface") @postmapping ("/comments") @Responsebody public dataGridResult Комментарии (CommentQuery Query) {// Установить по умолчанию 10 Query.setLimit (10); return commentservice.listCommentByArticleId (запрос); } @Apioperation (value = "articleLid") @apiimplicitarparam (name = "articleid", value = "articeid", refend = true, dataType = "long") @postmapping ("/uppure") @responsebody public yyblogresult uppree (@requestparam long articleid) {return articleservice. }}Наконец, есть рендеринг, такой же, как и выше.
Когда Pathselectors.none () есть
Когда PathseSelectors.ny () есть
С первого взгляда ясно, является ли содержание интерфейса рендерингом, и это очень кратко и ясно.
Наконец, кажется, что я забыл сказать путь к документу Swagger
Если ваш проект находится в корневом каталоге: http: // localhost: 8080/swagger-ui.html
Если это не корневой каталог, это: http: // localhost: 8080/wye name/swagger-ui.html
Выше всего содержание этой статьи. Я надеюсь, что это будет полезно для каждого обучения, и я надеюсь, что все будут поддерживать Wulin.com больше.