Краткое изложение чванства
Swagger - это RESTFUL интерфейсный документ онлайн, автоматическая генерация + функциональное программное обеспечение для тестирования. Swagger — это каноническая и полная платформа для создания, описания, вызова и визуализации веб-сервисов в стиле RESTful. Общая цель состоит в том, чтобы клиент и файловая система обновлялись с той же скоростью, что и сервер. Файловые методы, параметры и модели тесно интегрированы в серверный код, что позволяет постоянно синхронизировать API.
Spring Boot интегрирует Swagger
Строительная бумага: Чугерс
pom.xmlswagger должен ввести следующие банки
<!-- 引入swagger包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
@EnableSwagger2Используйте аннотацию @EnableSwagger2 в классе Control, чтобы включить функциональность swagger.
@RestController
@EnableSwagger2 // 启动swagger注解
// api-value：定义名称，如果没有定义，则默认显示类名
@Api(value = "Swagger Test Control", description = "演示Swagger用法的Control类", tags = "Swagger Test Control Tag")
public class SwaggerTestCtl {
..
}
Выполнить стартовый классВыполните класс запуска и получите доступ к следующим соединениям http://127.0.0.1:8080/swagger-ui.html#/ Вы можете войти на страницу swagger, чтобы протестировать интерфейс.Интерфейс выглядит следующим образом:
Класс АпиИнфо
Мы создаем экземпляр APIINFO, и мы настраиваем больше описаний интерфейса для Swagger
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
// .pathMapping("/")// base，最终调用接口后会和paths拼接在一起
.select()
// .paths(Predicates.or(PathSelectors.regex("/api/.*")))//过滤的接口
.apis(RequestHandlerSelectors.basePackage("com.hry.swagger.ctl")) //过滤的接口
.paths(PathSelectors.any())
.build();
}
private ApiInfo getApiInfo() {
// 定义联系人信息
Contact contact = new Contact("hryou0922","https://github.com/hryou0922", "hryou0922@126.com");
return new ApiInfoBuilder()
.title("演示 Swagger 的用法") // 标题
.description("演示Swagger中各种注解的用法") // 描述信息
.version("1.1.2") // //版本
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.contact(contact)
.build();
}
Перезапускаем сервис, интерфейс такой:
чванливые аннотации
Обзор аннотаций swagger
Мы можем использовать swagger для определения более подробных описаний интерфейса.
@Api：用在类上，标志此类是Swagger资源
value：接口说明
tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息
@ApiOperation：用在方法上，描述方法的作用
@ApiImplicitParams：包装器：包含多个ApiImplicitParam对象列表
@ApiImplicitParam：定义在@ApiImplicitParams注解中，定义单个参数详细信息
○ paramType：参数放在哪个地方
§ header-->请求参数的获取：@RequestHeader
§ query-->请求参数的获取：@RequestParam
§ path（用于restful接口）-->请求参数的获取：@PathVariable
§ body（以流的形式提交 仅支持POST）
§ form（以form表单的形式提交 仅支持POST）
○ name：参数名
○ dataType：参数的数据类型 只作为标志说明，并没有实际验证
§ Long
§ String
○ required：参数是否必须传
§ true
§ false
○ value：参数的意义
○ defaultValue：参数的默认值
@ApiModel：描述一个Swagger Model的额外信息
@ApiModel用在类上，表示对类进行说明，用于实体类中的参数接收说明
@ApiModelProperty：在model类的属性添加属性说明
@ApiParam：用于Controller中方法的参数说明
@ApiResponses：包装器：包含多个ApiResponse对象列表
@ApiResponse：定义在@ApiResponses注解中，一般用于描述一个错误的响应信息
○ code：错误码，例如400
○ message：信息，例如"请求参数没填好"
○ response：抛出异常的类
@Authorization Declares an authorization scheme to be used on a resource or an operation.
@AuthorizationScope Describes an OAuth2 authorization scope.
##Демонстрация с использованием аннотации В этом разделе мы покажем, как использовать аннотации из предыдущего раздела. ###@Апи Используется в классах, указывает на то, что этот класс является ресурсом Swagger, а интерфейс более детализирован.
@RestController
@EnableSwagger2 // 启动swagger注解
@Api(value = "Swagger Test Control", description = "演示Swagger用法的Control类", tags = "Swagger Test Control Tag")
public class SwaggerTestCtl {
}
Результаты приведены ниже:
### @ Апиоперация Используется в методах, роль метода
// 方法的说明
@ApiOperation(value = "根据id获取记录", response = Student.class)
// 定义请求参数
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主键", required = true) })
public Student queryById(String id){
System.out.println("queryById id = " + id);
return new Student();
}
Результат выглядит следующим образом:
@ApiImplicitParams и @ApiImplicitParam
// 定义请求参数
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "String", name = "id", value = "主键", required = true) })
public Student queryById(String id){
System.out.println("queryById id = " + id);
return new Student();
}
Результат выглядит следующим образом:
###@ApiModel и @ApiModelProperty
Определите класс модели
@ApiModel( description = "学生")
public class Student {
@ApiModelProperty(value = "主键id")
private String id;
@ApiModelProperty(value = "名称", required = true)
private String name;
@ApiModelProperty(value = "年龄", required = true)
private int age;
…
}
По способу использования
@RequestMapping(value = "/update", method = {RequestMethod.POST})
// 方法说明
@ApiOperation(value = "添加学生记录", notes="传递复杂对象DTO",produces = "application/json")
public int update(@RequestBody Student student){
System.out.println("update student = " + student);
return 1;
}
Результат выглядит следующим образом:
@ApiResponses и @ApiResponse
@RequestMapping(value = "/del", method = {RequestMethod.POST, RequestMethod.GET})
// 方法说明
@ApiOperation(value = "删除学生记录学生记录")
// 定义返回值意义
@ApiResponses({
@ApiResponse(code = 400, message = "服务器内部异常"),
@ApiResponse(code = 500, message = "权限不足") })
public int del(int id){
System.out.println("del id = " + id);
return 1;
}
Результат выглядит следующим образом:
разное
Во время теста содержимое интерфейса может не обновляться, для принудительного обновления можно использовать Shift+F5
код
Подробный код выше показан нижекод github, попробуйте использовать тег v0.22, не используйте мастер, потому что я не могу гарантировать, что мастер-код останется неизменным