Spring Boot 2.x (12): правильный способ играть в Swagger2

Spring Boot

Введение в Swagger2

Проще говоря, Swagger2 был рожден для решения проблемы общения между фронтенд- и бэкенд-разработчиками.Документацию по API сложно поддерживатьЕго можно идеально сочетать с нашей программой Java и использовать вместе с другим нашим инструментом разработки, Spring Boot.

начать использовать

Шаг 1: импортируйте файл POM

 		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency> 
        
		<!-- 这里使用 swagger-bootstrap-ui 替代了原有丑陋的ui，拯救处女座~ -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.0</version>
        </dependency>

Шаг 2. Добавьте класс конфигурации

Нам нужно добавить класс конфигурации Swagger2Config:

/**
 *	Swagger2 配置类
 * @author vi	
 * @since 2019/3/6 8:31 PM
 */
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("indi.viyoung.viboot.*"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("viboot-swagger2")	//标题
                .description("Restful-API-Doc")	//描述
                .termsOfServiceUrl("https://www.cnblogs.com/viyoung") //这里配置的是服务网站，我写的是我的博客园站点~欢迎关注~
                .contact(new Contact("Vi的技术博客", "https://www.cnblogs.com/viyoung", "18530069930@163.com")) // 三个参数依次是姓名，个人网站，邮箱
                .version("1.0") //版本
                .build();
    }
}

Шаг 3. Добавьте конфигурацию в класс запуска.

Обязательно не забудьте добавить@EnableSwagger2аннотация

/**
 * @author vi
 * @since 2019/3/6 6:35 PM
 */
@SpringBootApplication
@ComponentScan(value = "indi.viyoung.viboot.*")
@MapperScan(value = "indi.viyoung.viboot.swagger2.mapper")
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class ViBootSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ViBootSwaggerApplication.class, args);
    }
}

Шаг 4. Заполните документацию по API с помощью аннотаций.

1. @Api
Название аннотации Свойства аннотации сфера эффект атрибута
@Api tags своего рода Объясните, что делает класс
value своего рода Объясните, что делает класс

Например 🌰:

@Api(value = "用户类控制器",tags="用户类控制器")
public class UserController {
...
}

2 . @ApiOperation
Название аннотации Свойства аннотации сфера эффект атрибута
@ApiOperation() value метод метод описания
notes метод Советы
tags метод группировка

Например 🌰:

 	@ApiOperation(value = "获取用户列表",notes = "获取用户列表")
    public List<User> get() {
     	...   
	}

3. @ApiParam
Название аннотации Свойства аннотации сфера эффект атрибута
@ApiParam() name параметры метода имя параметра
value параметры метода Параметр Описание
required параметры метода Требуется ли

Например 🌰:

	@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    public User get(@ApiParam(name="id",value="用户id",required=true) Long id) {
        log.info("GET..{}...方法执行。。。",id);
        return userService.getById(id);
    }

4. @ApiModel && @ApiModelProperty
Название аннотации Свойства аннотации сфера эффект атрибута
@ApiModel() value своего рода имя объекта
description своего рода описывать
@ApiModelProperty() value метод Поле Описание
name метод Имя свойства
dataType метод тип недвижимости
required метод Требуется ли
example метод Пример
hidden метод Спрятать

Например 🌰:

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value = "用户ID",example = "1000001",hidden=true)
    private Long id;

    @ApiModelProperty(value="用户名",required = true,dataType = "String")
    private String userName;
    
    @ApiModelProperty(value = "密码")
    private String password;
}

5. @ApiImplicitParam && @ApiImplicitParams
`@ApiImplicitParam`可以单个用于方法至上，多个参数的话可以把`@ApiImplicitParam`放到`@ApiImplicitParams`中，这里只罗列`@ApiImplicitParam`的属性：
Название аннотации Свойства аннотации сфера эффект атрибута
@ApiImplicitParam() value метод Параметр Описание
name метод имя параметра
dataType метод тип данных
paramType метод Тип параметра
example метод Пример

Например 🌰:

	@ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    public void put(User user) {
        userService.updateById(user);
        log.info("PUT方法执行。。。");
    }

Здесь следует отметить, что мы не написали два параметра в кружке на рисунке в аннотации.Userаннотацию класса и установите имя пользователя по мере необходимости!

6.@ApiResposne && @ApiResponses

@ApiResponsesи@ApiResponseотношения и@ApiImplicitParam && @ApiImplicitParamsОтношения и использование аналогичны

Название аннотации Свойства аннотации сфера эффект атрибута
@ApiResponse() response метод возвращаемый класс
code метод код возврата
message метод возвращенные сообщения
examples метод пример

Наконец, давайте поговорим об этом пользовательском интерфейсе.

Сначала опубликуйте несколько пользовательских интерфейсов spring-fox (именно тот, с которым мы знакомы)

Я считаю, что увидев это, у каждого должен быть ответ на выбор этих двух наборов пользовательского интерфейса.Конечно, пользовательский интерфейс в стиле начальной загрузки не только красив, но также имеет различные мощные функции~

  1. экспортировать md-файл

  2. кэш параметров

публика

Оригинал статьи, ограниченный стиль написания, недостаток знаний и знаний, если есть неточности в статье, сообщите пожалуйста.

Категории