Интерфейс Springboot + swagger документирует корпоративную практику (включено)

Java Swagger

tags: springboot swagger doc

Вкратце в одном предложении: для разработки продукта, особенно в режиме разработки с разделением клиентской и серверной части, документ интерфейса является хабом, соединяющим интерфейс и серверную часть. В этой статье описывается практика springboot + swagger в предприятие в деталях.

1. Введение

В процессе разработки программного обеспечения дизайн интерфейса и документация по интерфейсу являются важной частью, особенно в случае разделения внешнего и внутреннего интерфейса, документация по интерфейсу является связующим звеном между разработчиками. Существует много способов написания документов интерфейса, вы можете использовать слово или инструменты для письма, такие как Xiao Yaoji. В основном это документы, написанные из кода. Если интерфейс меняется, вам нужно изменить документы и увеличить рабочую нагрузку. Как повысить эффективность написания документов интерфейса?При разработке Springboot рекомендуется сочетать swagger для предоставления описаний документов интерфейса.Благодаря настройке и аннотации в процессе написания кода интерфейса также пишутся документы интерфейса.Когда интерфейс необходимо изменить, документы также меняются одновременно, что имеет преимущества меньшей рабочей нагрузки, высокой эффективности, интуитивно понятного и лаконичного интерфейса документов и проверки вызовов в режиме реального времени. Эта статья основана на springboot2+swagger2 в сочетании с практикой на предприятии, чтобы подробно описать подготовку документа интерфейса следующим образом:

  • Введение в Swagger и инструкции по созданию документов
  • Используйте springboot2+swagger2 для создания примера проекта и описания конфигурации.
  • Используйте аннотации для добавления описаний содержимого документа
  • Аутентификация интерфейса с использованием глобальных параметров

Чтобы увидеть исходный код, эта статьяПример адреса проекта:https://github.com/mianshenglee/my-example

2. Введение в Swagger

2.1 Введение в чванство

swaggerАдрес официального сайта:https://swagger.io, как видно с официального сайта, это спецификация (OpenAPI Specification, OAS) и полный фреймворк (такой как редактор Swagger Editor, компонент отображения Swagger Editor, генерация кода Swagger Codegen) для генерации, описания, вызова и визуализации веб-сайтов в стиле RESTful. услуга. Поскольку это спецификация, она определяет ряд правил, связанных с описанием интерфейса, таких как формат документа, структура файла, тип данных, метод запроса и т. д., которые могут бытьОбратитесь к официальной спецификации:https://swagger.io/specification/v2/, файлы обычно проектируются и записываются в формате YAML (удобный для записи), а для передачи используется JSON (сильная универсальность). После того, как у вас есть файл описания интерфейса, вам нужно отобразить его в понятном виде.Swagger-UI:https://swagger.io/tools/swagger-ui/. Функция этого компонента — отображать yaml-файл, написанный по спецификации, в виде документа интерфейса. Мы можем загрузить этот компонент для локального запуска, это статическая веб-страница, и поместить его в веб-контейнер (например, apache, nginx) для запуска. Вы также можете воспользоваться онлайн-версией официального сайта. следующее:

Swagger-UI

На данный момент мы знаем, что шаги по использованию swagger для написания документов интерфейса: (1) написание файлов интерфейса, совместимых с OAS, (2) использование swagger-ui для отображения.

2.2 спрингфокс, чванство и спрингбут

Как видно спереди, написание файлов интерфейса, соответствующих OAS, по-прежнему приходится писать вручную, а отображение swagger-ui неудобно (требуется ручное автономное развертывание или использование онлайн-сервисов).Теперь веб-разработка в области java в основном разработан с использованием springmvc.Это удобнее?Как совместить swagger для написания файлов интерфейса без ручного написания и снижения нагрузки?

крупный рогатый скотMarty PittНаписал пружинный компонентswagger-springmvc:https://github.com/martypitt/swagger-springmvc-example, используемый для интеграции swagger в springmvc. Springfox разработан на основе этого компонента, он может автоматически генерировать документы JSON API на основе Spring, а теперь и черезhttps://github.com/martypitt/swagger-springmvc/Адрес сразу перейдет кСтраница Springfox на github,этоОфициальный сайт:http://springfox.io. В настоящее время Springfox выпустил несколько версий, в этой статье используетсяspringfox-swagger2Версия 2.7.0. Для Swagger-ui это также обеспечиваетspringfox-swagger-ui, страница отображения документации по интерфейсу интеграции. Таким образом, оба шага предыдущего swagger могут выполняться автоматически. Сейчас мы в основном используем springboot для разработки java веб-приложений, использование его автоматической настройки и аннотаций более удобно для разработки. Поэтому, исходя из спецификации swagger, использование компонентов springfox (swagger2 и swagger-ui) в сочетании с springboot может сделать документацию по интерфейсу очень простой и эффективной. В общем, springfox — это автоматизированная реализация спецификации swagger в разработке springmvc и springboot. Ниже приводится конкретное описание использования таким образом.

3. Используйте springboot+swagger для создания документации по интерфейсу

В этой главе Springboot2+swagger2 будет использоваться для создания примерного проекта и описания базовой конфигурации.

3.1 Создание примера проекта Springboot

(1) Создать проект: передатьСтраница Spring InitializrСоздайте пустой проект Spring Boot и добавьте веб-зависимости.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

(2) Напишите пример интерфейса:

  • Сначала добавьте несколько общих пакетов: vo, controller, service, model, exception, в которых хранится код модели уровня представления, уровня управления, уровня сервиса, уровня модели данных, объекта исключения и т. д. соответственно.
  • Примером модели данных является User, что соответствует UserController, UserService, модели унифицированного представления возврата ResponseResult и унифицированному классу исключений UniRuntimeException.
  • Для управления пользователями используется спокойный интерфейс для определения добавления, удаления, изменения и запроса пользователей, соответствующих запросам (POST, DELETE, PUT, GET), следующим образом:
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;
    
    /**
     * 查询单个用户
     */
    @GetMapping("/{userId}")
    public ResponseResult getUserById(@PathVariable long userId) {...}
    /**
     * 查询多个用户
     */
    @GetMapping()
    public ResponseResult getUsers() {...}
    /**
     * 添加多个用户
     */
    @PostMapping()
    public ResponseResult addUsers(@RequestBody List<User> users) {...}
    /**
     * 添加单个用户
     */
    @PostMapping("/user")
    public ResponseResult addUser(@RequestBody User user) {...}
    /**
     * 更新单个用户
     */
    @PutMapping("/user")
    public ResponseResult updateUser(@RequestBody User user) {...} 
    /**
     * 删除单个用户
     */
    @DeleteMapping("/user")
    public ResponseResult deleteUser(long userId) {...}
}

Примечание. Здесь мы сосредоточимся только на определении, параметрах и возвращаемых значениях интерфейса, конкретные сущности не перечислены (подробнее см.исходный код:https://github.com/mianshenglee/my-example).

На данный момент пример проекта может работать нормально со следующими интерфейсами:

  1. GET /users/{userId}Получить одного пользователя
  2. GET /usersПолучите несколько пользователей
  3. POST /usersДобавить несколько пользователей
  4. POST /users/userДобавить одного пользователя
  5. PUT /users/userОбновить одного пользователя
  6. DELTE /users/user?userId=xxудалить одного пользователя

Примечание: Для RequestMapping интерфейса, если httpMethod не указан, springfox перечислит все методы GET/POST/PUT/PATCH/DELETE этого метода, поэтому при написании интерфейса укажите фактическое действие.

3.2 Знакомство с swagger2 и базовой конфигурацией

3.2.1 Добавление зависимости springfox-swagger

Чтобы автоматически генерировать файлы описания интерфейса, совместимые с swagger, вам необходимо добавить зависимости springfox следующим образом:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

3.2.2 Настройка чванства

Добавьте пакет конфигурации для хранения файла конфигурации и добавьте следующее Swagger2Config.java, следующим образом:

@Configuration
@EnableSwagger2
public class Swagger2Config {
private ApiInfo apiInfo() {
	@Bean
	public Docket api(){
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any())
				.build();
	}
    private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("接口说明文档")
				.description("API文档描述")
				.version("0.0.1-SNAPSHOT")
				.build();
	}
}

Этот файл настраивает bean-компоненты Docket, включая базовую информацию API, отображаемые интерфейсы (apis) и пути для фильтрации (пути), чтобы можно было сгенерировать документы интерфейса, соответствующие спецификации.

3.2.3 Просмотр документа описания, автоматически сгенерированного swagger

После интеграции swagger2 с использованием приведенной выше конфигурации запустите проект и введитеhttp://localhost:8080/swaggerdemo/v2/api-docsВы можете просмотреть документ с описанием интерфейса в формате JSON. Следующее:

1573465257350

Этот документ соответствует спецификации OAS, но он находится в одном шаге от визуального отображения и использования, то есть того, как отображать эту информацию на интерфейсе.

3.3 Добавление взаимодействия интерфейса swagger-ui

Чтобы визуально отображать интерфейсные документы, SpringFox предоставил интерфейс отображения компонентов, добавив следующие зависимости:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

После добавления этой зависимости представленный пакет springfox-swagger-ui.jar содержитswagger-ui.htmlстраница, используя адресhttp://localhost:8080/swaggerdemo/swagger-ui.htmlВы можете просмотреть страницу документации интерфейса. В этом документе вы можете просмотреть определения интерфейса, входные параметры, возвращаемые значения или использоватьtry it outВызов интерфейса для отладки. следующее:

1573465932646

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

  • Вы не можете выбрать отображение документов в соответствии со средой (возможно, среда разработки должна отображаться, а формальная среда - нет)
  • Интерфейс не имеет описания функций и подробного описания
  • Подробное описание входного параметра и пример описания
  • Подробное описание и пример описания возвращаемого значения
  • Возвращаются все интерфейсы контроллера, и нет необходимости фильтровать нужные интерфейсы
  • Все интерфейсы можно отладить, но есть проблема с аутентификацией авторизации

Эти проблемы необходимо решать в практике предприятия.

4. [Практика предприятия] Параметризация конфигурации и фильтрация пакетов

4.1 Параметризация конфигурации

Документ интерфейса обычно содержит основную информацию о документе, включая название документа, описание, версию интерфейса, контактную информацию и т. д. swagger предоставил соответствующие элементы конфигурации, например, в приведенном выше примере.apiInfo(), напишите основную информацию в коде для конфигурации, которая не является дружественной к модификации.Поэтому лучше всего параметризовать эти конфигурации, чтобы сформировать независимый файл конфигурации swagger, чтобы избежать изменений кода, вызванных изменением базовой информации.

4.1.1 Добавить файл конфигурации с базовой информацией

существуетresources/configкаталог, добавитьswagger.propertiesфайла, поместите информацию о конфигурации в этот файл.

swagger.basePackage =me.mason.helloswagger.demo.controller
swagger.title = 应用API说明文档
swagger.description = API文档描述
swagger.version = 0.0.1-SNAPSHOT
swagger.enable = true
swagger.contactName = mason
swagger.contactEmail =
swagger.contactUrl =
swagger.license =
swagger.licenseUrl =

соответственно, вconfigПод пакетом добавьте объект SwAgwanfo, соответствующий вышеуказанному файлу конфигурации:

@Component
@ConfigurationProperties(prefix = "swagger")
@PropertySource("classpath:/config/swagger.properties")
@Data
public class SwaggerInfo {
    private String basePackage;
    private String antPath;
    private String title = "HTTP API";
    private String description = "Swagger 自动生成接口文档";
    private String version ;
    private Boolean enable;
    private String contactName;
    private String contactEmail;
    private String contactUrl;
    private String license;
    private String licenseUrl;
}

Официальная рекомендация заключается в том, что для этой пользовательской конфигурации лучше всего добавить следующееspring-boot-configuration-processorЗависимость для генерации метаданных конфигурации, иначе в IDEA будет"spring boot configuration annotation processor not found in classpath"Предупреждение:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

4.1.2 Документ с интегрированной конфигурацией swagger

имеютSwaggerInfoКласс конфигурации, который интегрирует swagger2apiInfo()Его можно внедрить и использовать, и вы можете изменить файл конфигурации, когда вам нужно будет изменить его позже.

private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title(swaggerInfo.getTitle())
        .description(swaggerInfo.getDescription())
        .version(swaggerInfo.getVersion())
        .licenseUrl(swaggerInfo.getLicenseUrl())
        .contact(
            new Contact(swaggerInfo.getContactName()
            ,swaggerInfo.getContactUrl()
            ,swaggerInfo.getContactEmail()))
        .build();
}

4.2 Настройка включения документов

Для разных сред может потребоваться включение и отключение документа интерфейса, например, в среде разработки нам нужно отображать документ интерфейса, но в официальной онлайн-среде иногда мы не хотим публиковать интерфейс в внешний мир. Это требование можно использоватьenableВы можете настроить его в сочетании с файлом конфигурацииswagger.enableЭлемент конфигурации (false для отключения, true для включения). следующее:

.enable(swaggerInfo.getEnable())

4.3 Фильтрация пакетов

Компонент swagger будет автоматически сканироватьControllerаннотации иRequestMappingАннотированный интерфейс, преобразованный в описание интерфейса. В процессе разработки мы не хотим, чтобы отображались все интерфейсы в проекте, а хотим отображать интерфейсы под определенным пакетом. инструкцииapis(), в сочетании с файлом конфигурации, для достижения этого эффекта. в файле конфигурацииswagger.basePackageКонфигурация (несколько пакетов разделены знаком «;»). Добавьте следующую функцию фильтра:

private List<Predicate<RequestHandler>> apisFilter() {
    List<Predicate<RequestHandler>> apis = new ArrayList<>();
    String basePackageStr = swaggerInfo.getBasePackage();
    //包过滤
    if (StrUtil.isNotEmpty(basePackageStr)) {
        //支持多个包
        String[] basePackages = basePackageStr.split(";");
        if (null != basePackages && basePackages.length > 0) {
            Predicate<RequestHandler> predicate = input -> {
                // 按basePackage过滤
                Class<?> declaringClass = input.declaringClass();
                String packageName = declaringClass.getPackage().getName();
                return Arrays.asList(basePackages).contains(packageName);
            };
            apis.add(predicate);
        }
    }
    return apis;
}

Вышеуказанная функция сравнивает отсканированный интерфейс с настроенным пакетом и возвращает его под настроенным пакетом, в противном случае он отфильтровывается. Затем при настройке Docket добавьте этот фильтр.

builder = builder.apis(Predicates.or(apisFilter()));

используется здесьPredicates.or, что означает выполнить операцию ИЛИ над возвращенным, и будет отображаться истинный.

5. [Практика предприятия] Используйте аннотации для добавления содержимого документа

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

  1. Аннотации модели данных:@ApiModel, описание сущности;@ApiModelProperty, описание атрибута объекта
  2. Аннотация интерфейса:@ApiOperation, Описание интерфейса;@ApiIgnore, игнорировать этот интерфейс
  3. Аннотации контроллера:@Api, описание контроллера
  4. Комментарии к входным параметрам:@ApiImplicitParams, несколько параметров интерфейса;@ApiImplicitParam, один параметр;@ApiParam, описание одного параметра
  5. Аннотация данных ответа:@ResponseHeader, заголовок значения ответа;@ApiResponses, набор значений ответа;@ApiResponse, одно значение ответа

Ниже мы объясним использование аннотаций и используем аннотации для добавления описаний интерфейса в примере.

5.1 Модель данных (MODEL) Примечание Инструкции

В процессе разработки M (Model) используется для передачи данных для интерфейса шаблона MVC, поэтому требуется эффективное описание этой модели данных. Соответствующие аннотации:

  • @ApiModel: описание объекта
  • @ApiModelProperty: Описание атрибута объекта.

Таблица ниже@ApiModelPropertyИнструкции по применению:

Свойства аннотации тип описывать
value String Описание поля.
name String Переопределить имена полей.
dataType Stirng Переопределить тип поля.
required boolean Необходимые.
example Stirng Например.
hidden boolean Скрывать ли поле в документе.
allowEmptyValue boolean Разрешить ли null.
allowableValues String Допустимые значения для этого поля.

В данном примере этоUserКлассы описываются с использованием следующих аннотаций:

@ApiModel
public class User {
    @ApiModelProperty(value="id",required = true,example = "1")
    private long id;
    @ApiModelProperty(value="姓名",required = true,example = "张三")
    private String name;
    @ApiModelProperty(value="年龄",example = "10")
    private int age;
    @ApiModelProperty(value="密码",required = true,hidden = true)
    private String password;
}

Таким образом, в документации интерфейса используйтеUserВ качестве входных параметров можно посмотреть описание этой модели следующим образом:

1573550660883

5.2 Контроллер и интерфейс Примечание

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

  • @ApiIgnore: документация Swagger не будет отображать интерфейсы с этой аннотацией.

  • @Api: описание контроллера

Свойства аннотации тип описывать
tags String[] Этикетка контроллера.
description String Описание контроллера (это поле объявлено как просроченное).
  • @ApiOperation: Описание интерфейса.
Свойства аннотации тип описывать
value String Описание интерфейса.
notes String Примечания к выпуску интерфейса.
tags Stirng[] Этикетка.
response Class<?> Тип возврата интерфейса.
httpMethod String Метод запроса интерфейса.

В этом примере вUserControllerСоответствующие описания следующие:

@Api(tags = "用户管理接口", description = "User Controller")
public class UserController {
    @ApiOperation(value = "根据ID获取单个用户信息", notes = "根据ID返回用户对象")
    ...//省略
 @ApiOperation(value = "添加多个用户", notes = "使用JSON以数组形式添加多个用户")
    ...//其它
}

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

1573551666969

5.3 Аннотационное описание входных параметров интерфейса

Использование параметров контроллера 5.3.1 SpringMVC

Перед параметрами ввода интерфейса вводились пояснительные замечания Swagger, необходимо иметь четкое понимание параметров интерфейса SpringMVC. Мы знаем через SpringMVC@RequestMappingМетод соответствует URL-адресу запроса, а параметры необходимо передать контроллеру при вызове метода интерфейса. Вообще говоря, передача параметров SpringMVC включает в себя следующее:

  • Неаннотированные параметры
  • @RequestParamПараметры аннотации
  • параметр массива
  • Параметры объекта JSON
  • Параметры стиля REST

Для удобства объяснения, в настоящем примере,ParamDemoControllerфайл, в котором приведены примеры различных параметров, читатели могут обратиться к нему, ниже описаны эти параметры.

(1) Нет параметров аннотации

Чтобы получить параметры без аннотаций, имя параметра должно совпадать с именем параметра HTTP-запроса, и этот параметр может быть пустым. Следующий интерфейс:

@GetMapping("/no/annotation")
public Map<String,Object> noAnnotation(Integer intVal, Long longVal, String str){}

При вызове вы можете использоватьhttp://localhost:8080/no/annotation?inVal=10&longVal=100,параметрstrМожет быть пустым.

(2)@RequestParamПараметры аннотации

Используйте аннотацию RequestParam для получения параметров, вы можете указать сопоставление параметров HTTP и имен параметров метода, и он не может быть пустым (но его можно разрешить пустым, установив false в required). Следующий интерфейс:

@GetMapping("/annotation")
public Map<String,Object> annotation(@RequestParam("int_val") Integer intVal,@RequestParam("long_val") Long longVal,@RequestParam(value="str_val", required = false) String str){}

Метод вызова такой же, как и неаннотированный выше. но если не установленоrequired=false, вы должны пройти вstrпараметр.

(3) параметр массива

Используйте в качестве параметра массив, при вызове интерфейса используйте запятую (,) разделены. Следующий интерфейс:

@GetMapping("/array")
public Map<String,Object> requestArray(int[]intArr,long[]longArr,String[] strArr){}

Чтобы вызвать этот интерфейс, вы можете использоватьhttp://localhost:8080/array?intArr=10,11,12&longArr=100,101,102&strArr=a,b,c.

(4) Параметры объекта JSON

Когда передаваемые данные относительно сложны или связаны с определенной моделью, параметры должны быть собраны в JSON для передачи, который используется, когда внешний интерфейс вызывает интерфейс.JSONТело запроса, SpringMVC от@RequestBodyАннотация, которая реализует сопоставление параметров JSON и выполняет соответствующие преобразования объектов. следующее:

@PostMapping("/add/user")
public User addUser(@RequestBody User user){}

При вызове интерфейса используйте JSON для передачи параметров, получения параметров JSON через аннотацию RequestBody и сопоставления их с объектами User. Если это объект массива (списка), он также поддерживается.

(5) Параметры стиля REST

Для URL-адресов RESTful параметры записываются в URL-адрес, напримерusers/1,в1является параметром идентификатора пользователя. Для таких параметров SpringMVC использует@PathVariableреализация, которая использует{}作为占位符。 следующее:

@GetMapping("/users/{id}")
public User getUser(@PathVariable("id") Long id){}

5.3.2 Описание аннотации входного параметра swagger

Для параметров SpringMVC, упомянутых выше, Springfox выполнил автоматическую обработку вswagger-uiПри отображении в документе он также отображается в соответствии с типом параметра. В swagger типы параметров делятся на:

  • путь: отправьте данные в виде адреса, и интерфейс для запроса пользователей на основе идентификатора должен передавать параметры в этой форме.
  • query: метод строки запроса для передачи параметров, не соответствующих аннотации и@RequestParamПараметры аннотации
  • заголовок: параметры в заголовке запроса (header)
  • форма: Представлено в виде формы Форма, например, загрузка файла, относится к этой категории
  • body: передать параметры в JSON

При описании входных параметров swagger аннотирует следующее:

  • @ApiImplicitParams: Набор параметров, описывающий интерфейс.
  • @ApiImplicitParam: описать один параметр интерфейса и@ApiImplicitParamsиспользуется в комбинации.
  • @ApiParam: Опишите один параметр, необязательный.

в,@ApiParamИспользуется с одним параметром,@ApiImplicitParamИспользуемые в описании интерфейса, свойства этих двух в основном одинаковы.@ApiImplicitParamСвойства следующие:

Свойства аннотации описывать
paramType Тип параметра запроса, указывающий, где находится параметр, как указано выше, доступные значения: путь, запрос, заголовок, форма, тело.
dataType Тип данных параметра используется только как описание признака, фактической проверки нет, его можно заполнить в соответствии с фактическим типом, таким как String, User
name имя параметра
value Описание значения параметров
required Требуется: правда/ложь
allowMultiple Есть ли более одного, используйте при работе с объектами массива JSON
example Пример данных

В качестве массива объектов интерфейса JSON используется следующее:

@ApiOperation(value = "添加多个用户", notes = "使用JSON以数组形式添加多个用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "users", value = "用户JSON数组", required = true, dataType = "User",allowMultiple = true)
})
@PostMapping()
public ResponseResult addUsers(@RequestBody List<User> users) {}

В этом примере используйте@RequestBodyПримечание, передачаList<User>Поэтому параметр массива JSON используетallowMultipleсвойство, тип данныхUserИ егоparamTypeзаbody. swagger文档如下：

1573617046002

5.4 Описание аннотации данных ответа интерфейса

Для@RestControllerАннотированный контроллер, SpringMVC автоматически преобразует возвращаемые данные в данные json. В процессе разработки мы обычно единообразно инкапсулируем возвращаемые данные, возвращаемый статус, информацию, фактические данные и так далее. Как в этом примере сResponseResultВ качестве унифицированного возвращаемого результата возвращаемые данные используют дженерики (если дженерики не используются, последующее swagger не будет отображать атрибуты Модели при отображении возвращаемых результатов), как показано ниже.

@NoArgsConstructor
@AllArgsConstructor
@Data
public class ResponseResult<T> {
	@ApiModelProperty(value="返回状态",example = "true")
	private boolean success;
	@ApiModelProperty(value="错误信息代码")
	private String errCode;
	@ApiModelProperty(value="错误显示信息")
	private String errShowMsg;
	@ApiModelProperty(value="错误信息")
	private String errMsg;
	@ApiModelProperty(value = "返回数据",notes = "若返回错误信息，此数据为null或错误信息对象")
	private T resultData;
}

В возвращаемом значении интерфейса, если вы не используете дженерики для указания конкретной модели, возвращайте толькоResponseResult, будут отображаться только свойства в этом объекте, а содержимое конкретных resultData не может быть отображено, как показано ниже:

1573617582748

Поэтому для единого возврата необходимо указать конкретную возвращаемую модель, чтобы было соответствующее описание для фактической возвращаемой модели. следующее:

@ApiOperation(value = "获取所有用户", notes = "返回全部用户")
@GetMapping()
public ResponseResult<List<User>> getUsers() {}

1573619148261

Для ответных сообщений swagger предоставляет ответные сообщения по умолчанию 401, 403, 404, или вы можете указать интерфейс самостоятельно.Доступны следующие аннотации:

  • @ApiResponses: Набор ответных сообщений
  • @ApiResponses: Ответное сообщение, описывающее ответное сообщение об ошибке, с@ApiResponsesиспользовать вместе
  • @ResponseHeader: настройки заголовка ответа

6.【Практика предприятия】Аутентификация интерфейса

Для внешних интерфейсов обычно требуется проверка разрешений, и пользователи, которым необходимо войти в систему, могут вызывать их, в противном случае разрешений недостаточно. Для аутентификации безопасности API обычно существуют следующие режимы (см.чванливая документация:https://swagger.io/docs/specification/authentication/):

  • Базовая аутентификация: использованиеAuthorizationЗаголовки запросов, имя пользователя и пароль закодированы в Base64, например:Authorization: Basic ZGVtbzpwQDU1dzByZA==
  • Аутентификация носителя: использованиеAuthorizationЗаголовок запроса для создания зашифрованного токена с сервера символов, когда клиент отправляет запрос на этот запрос токена на сервер в виде волос учетных данных, формат токенаAuthorization: Bearer <token>
  • Сертификация ключей API: используйте заголовки запросов, параметры или файлы cookie для передачи только ключей, которые могут быть известны только клиенту и серверу.
  • OAuth2: открытый стандарт, который позволяет пользователям разрешать сторонним мобильным приложениям получать доступ к информации, которую они хранят у другого поставщика услуг, не сообщая стороннему мобильному приложению имя пользователя и пароль и не передавая все свои данные.

Для проектов Springboot с разделенными интерфейсом и сервером многие из них теперь используют метод аутентификации jwt (принадлежащий аутентификации Bearer), и вам нужно сначала получить токен, а затем добавить что-то вродеAuthorization: Bearer <token>Заголовок запроса для аутентификации интерфейса. В ответ на этот метод в Swagger есть следующие три метода:

  1. Добавить в описание параметра интерфейса@ApiImplicitParam, где тип параметраParamType=header
  2. Добавить глобальные параметры интерфейса
  3. Добавить контекст аутентификации безопасности

6.1 Добавьте параметры аутентификации интерфейса

Для интерфейса, который необходимо аутентифицировать, используйте его напрямую@ApiImplicitParam, где тип параметраParamType=headerТо есть описание параметров было введено ранее. следующее:

@ApiImplicitParam(name = "Authorization", value = "token，格式: Bearer &lttoken&gt", required = false, dataType = "String",paramType = "header")

Недостаток этого метода в том, что для каждого интерфейса нужно добавлять описание этого параметра, причем описание одно и то же, и работа повторяется.

6.2 Добавление глобальных параметров интерфейса

В конфигурации swagger методglobalOperationParametersМожно установить глобальные параметры.

//全局header参数
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("Authorization").description("token令牌")
    .modelRef(new ModelRef("string"))
    .parameterType("header")
    .required(true).build();
pars.add(tokenPar.build());
docket.globalOperationParameters(pars);

Недостаток этого метода также очевиден: поскольку задан глобальный параметр, этот параметр обязателен для всех интерфейсов, если для некоторых интерфейсов он не нужен, требуется специальная обработка.

6.3 Добавить контекст аутентификации безопасности

Установите режим аутентификации и используйте регулярные выражения для фильтрации интерфейсов, которые необходимо аутентифицировать, чтобы интерфейс swagger предоставлял унифицированный интерфейс аутентификации. следующее:

docket.securitySchemes(securitySchemes())
		.securityContexts(securityContexts());
...//省略
private List<ApiKey> securitySchemes() {
		return Lists.newArrayList(
				new ApiKey("Authorization", "Authorization", "header"));
	}
private List<SecurityContext> securityContexts() {
    return Lists.newArrayList(
        SecurityContext.builder()
        .securityReferences(defaultAuth())
        //正则式过滤,此处是所有非login开头的接口都需要认证
        .forPaths(PathSelectors.regex("^(?!login).*$"))
        .build()
    );
}
List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "认证权限");
    return Lists.newArrayList(
        new SecurityReference("Authorization", new AuthorizationScope[]{authorizationScope}));
}

После настройки вводим логин, эффект следующий:

1573630877692

7. Резюме

В этой статье подробно описывается использование swagger и корпоративная практика, в основном вводится принцип swagger, как использовать springboot и swagger для создания интерфейсных документов, параметризованная конфигурация и фильтрация пакетов swagger, подробное использование аннотаций swagger и аутентификация интерфейса. методы и т. д., пример кода, использованный в этой статье, помещен вgithub:https://github.com/mianshenglee/my-example, Заинтересованные студенты могут получить код и учиться вместе с примерами.

использованная литература

Прошлые статьи

Подпишитесь на мой официальный аккаунт, чтобы получить больше технических записей:

mason

Категории