Использование документации Swagger в проектах Spring Boot

Java

Swagger, также известный как Brother Stockings, утверждает, что позволяет программистам создавать интерфейсные документы во время написания кода.

Добавьте зависимости Swagger 2

существуетpom.xmlДобавьте необходимые зависимости для Swagger 2 в:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

Добавить конфигурацию Java для Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())
      .build();
  }
}

Описание аннотации Swagger

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

  • @Api: Украсьте весь класс, чтобы описать роль контроллера.
  • @ApiOperation: описать метод класса или интерфейс
  • @ApiParam: Один параметр Описание
  • @ApiModel: Получение параметров объекта
  • @ApiProperty: При получении параметров с объектом опишите поле объекта
  • @ApiResponse: HTTP-ответ с 1 описанием
  • @ApiResponses: общее описание ответа HTTP.
  • @ApiIgnore: Используйте эту аннотацию, чтобы игнорировать этот API.
  • @ApiImplicitParam: параметр запроса
  • @ApiImplicitParams: Несколько параметров запроса

Это наиболее часто используемые аннотации.

Другие специальные аннотации см. на странице https://github.com/swagger-api/swagger-core/wiki/Annotations.

Для получения дополнительной информации см.Документация по аннотациям Swagger

Добавьте контроллер и модель, чтобы проверить эффект

@Api(value = "用户管理", description = "用户信息的「增、删、查、改」操作")
@RestController
@RequestMapping(path = "/sample/users")
public class UserController {

  private static Map<Long, UserModel> users = Collections.synchronizedMap(new HashMap<>());

  @ApiOperation(value = "用户列表")
  @GetMapping(path = "/")
  public List<UserModel> getUserList() {
    return new ArrayList<>(users.values());
  }

  @ApiOperation(value = "创建用户", notes = "根据 User 对象创建用户")
  @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataTypeClass = UserModel.class)
  @PostMapping(path = "/")
  public UserModel createUser(@RequestBody UserModel user) {
    users.put(user.getId(), user);
    return user;
  }

  @ApiOperation(value = "用户详细信息", notes = "根据 ID 获取用户详细信息")
  @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long")
  @GetMapping(path = "/{id}")
  public UserModel getUser(@PathVariable Long id) {
    return users.get(id);
  }

  @ApiOperation(value = "更新用户详细信息", notes = "根据 ID 指定更新对象, 并根据 User 信息来更新用户详细信息")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataTypeClass = Long.class),
      @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataTypeClass = UserModel.class)
  })
  @PutMapping(path = "/{id}")
  public UserModel updateUser(@PathVariable Long id, @RequestBody UserModel user) {
    UserModel updateUser = users.get(id);
    updateUser.setName(user.getName());
    updateUser.setAge(user.getAge());
    updateUser.setEmail(user.getEmail());
    users.put(id, updateUser);
    return updateUser;
  }

  @ApiOperation(value = "删除用户", notes = "根据 ID 指定删除对象")
  @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long")
  @DeleteMapping(path = "/{id}")
  public String deleteUser(@PathVariable Long id) {
    users.remove(id);
    return "success";
  }
}

@Data
@ApiModel(value = "用户模型", description = "用户详细信息实体类")
public class UserModel {

  @ApiModelProperty(value = "用户 ID")
  private Long id;

  @ApiModelProperty(value = "名字", allowableValues = "y0ngb1n, tony")
  private String name;

  @ApiModelProperty(value = "年龄", allowableValues = "range[1, 120]")
  private Integer age;

  @ApiModelProperty(value = "邮箱")
  private String email;
}

На этом этапе вы можете запустить проект, чтобы проверить, успешно ли интегрирован Swagger 2. После запуска проекта вы можете увидеть в журнале, что Swagger добавил для нас конечные точки доступа./v2/api-docs:

...
2019-12-28 22:19:53.880  INFO 11935 --- [main] pertySourcedRequestMappingHandlerMapping : Mapped URL path [/v2/api-docs] onto method [public org.springframework.http.ResponseEntity<springfox.documentation.spring.web.json.Json> springfox.documentation.swagger2.web.Swagger2Controller.getDocumentation(java.lang.String,javax.servlet.http.HttpServletRequest)]
...

Доступ через браузерhttp://localhost:8080/v2/api-docs, вы можете обнаружить, что возвращенный результат представляет собой строку JSON, которая очень плохо читается. К счастью, Swagger 2 предоставляет нам визуальный интерактивный интерфейс SwaggerUI, давайте попробуем его вместе.

Добавить зависимость пользовательского интерфейса Swagger

Как и выше, вpom.xmlДобавьте необходимые зависимости для пользовательского интерфейса Swagger в:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

После завершения добавления перезапустите проект, а затем зайдите через браузерhttp://localhost:8080/swagger-ui.html, чтобы увидеть следующий эффект:

Swagger 2

На данный момент интеграция Swagger прошла успешно. Для более сложных операций мы продолжим читать документацию или справочные ссылки ниже для дальнейшего изучения. Желаю вам счастливого обучения!

🔗️ Ссылка на ссылку

  • https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
  • https://www.tutorialspoint.com/springboot/springbootenablingswagger2.htm
  • http://blog.didispace.com/tags/Swagger/
  • https://www.ibm.com/developerworks/cn/java/j-using-swagger-in-a-spring-boot-project/index.html
  • https://mp.weixin.qq.com/s/EYnL7T0yOgNXYIrBWBg8hg
  • https://github.com/dyc87112/swagger-butler
  • https://github.com/SpringForAll/spring-boot-starter-swagger
  • https://blog.csdn.net/lilyssh/article/details/82944507

---

Спасибо за прочтение этой статьи отБлог Ян Бинавсе права защищены. При перепечатке указывать источник: блог Ян Бина (https://y0ngb1n.github.io?utm_source=juejin)

Проект размещен на GitHub:y0ngb1n/spring-boot-samples, добро пожаловать в Звезду, Вилку 😘

Категории