SpringBoot配置Swagger(踩坑泪编)

Swagger 又称丝袜哥,号称可以让程序员边写代码边生产接口文档。

添加 Swagger 2 依赖

在 pom.xml 中添加 Swagger 2 所需依赖:

<!-- swgger工具包2 -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>

<!-- 用来解决高版本Swgger2报错冲突 -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>

<!-- 用来可视化UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

Swagger 注解说明

Swagger 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

@Api:修饰整个类,描述 Controller 的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP 响应其中 1 个描述
@ApiResponses:HTTP 响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数

添加 Controller、Model 来测试效果

@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,下面我们就一起来试试吧。

然后通过浏览器访问 http://localhost:8080/swagger-ui.html,便以看到下面就效果:
请添加图片描述

踩坑:

springboot swagger2 出现报错No mapping for GET /swagger-ui.html:
如果继承了WebMvcConfigurationSupport,例如配置了拦截器,则在yml中配置的相关内容会失效。 需要重新指定静态资源
在当前继承WebMvcConfigurationSupport的配置类加上如下代码:

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations(
            "classpath:/static/");
    registry.addResourceHandler("swagger-ui.html").addResourceLocations(
            "classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations(
            "classpath:/META-INF/resources/webjars/");
    super.addResourceHandlers(registry);
}
### 回答1: SpringBoot 配置Swagger 可以参考以下步骤:1. 在pom.xml中添加Swagger2依赖;2. 在SpringBoot启动类中添加@EnableSwagger2注解;3. 创建配置Swagger2;4. 在配置类中配置Swagger2信息;5. 启动SpringBoot项目,访问Swagger2页面。 ### 回答2: Spring Boot是一个基于Java的快速开发框架,可以简化Java应用的搭建和开发过程。Swagger是一个RESTful API文档生成工具,它可以通过注解来生成API文档,并且提供了一个可交互的UI界面,方便开发人员查看和测试API接口。 要在Spring Boot项目中配置Swagger,需要进行以下步骤: 1. 导入Swagger依赖:在项目的pom.xml文件中添加Swagger的依赖项,通常是通过引入`springfox-swagger2`和`springfox-swagger-ui`这两个依赖来实现。 2. 创建Swagger配置类:在项目中创建一个Swagger配置类,用于配置Swagger的相关信息和接口扫描规则。可以在配置类中使用`@EnableSwagger2`注解来启用Swagger。 3. 配置Swagger的基本信息:在配置类中使用`Docket`类的实例来配置Swagger的基本信息,比如Swagger接口文档的版本、标题、描述、联系人等。可以通过`apiInfo`方法来设置这些信息。 4. 配置接口扫描规则:在配置类中使用`select`方法来设置Swagger要扫描的接口规则,比如指定要扫描的包路径,或者使用`RequestHandlerSelectors`类提供的方法来选择要包含的接口。 5. 配置Swagger UI界面:在配置类中使用`apis`方法来设置Swagger要显示的接口,可以选择显示所有接口,或者只显示带有特定注解的接口。可以使用`PathSelectors`类提供的方法来选择要显示的接口。 6. 启动项目并访问Swagger UI:完成上述配置后,启动Spring Boot项目,并访问Swagger UI界面,通常是通过在浏览器中访问`http://localhost:port/swagger-ui.html`来查看API文档。 以上就是在Spring Boot项目中配置Swagger的基本步骤。配置完毕后,开发人员就可以方便地查看和测试API接口,提高开发效率。 ### 回答3: Spring Boot是一个开源的Java开发框架,可以简化Spring应用程序的配置和开发过程。Swagger是一个用于构建、文档化和调试RESTful API的工具。在Spring Boot项目中配置Swagger可以使得我们更方便地管理和测试API接口。 要配置Swagger,我们需要在Spring Boot项目的pom.xml文件中添加Swagger的依赖。可以通过以下代码完成添加: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> ``` 添加依赖后,我们需要创建一个配置类来配置Swagger。可以创建一个名为SwaggerConfig的类,并通过@Configuration注解将其标记为配置类。在SwaggerConfig类中,我们需要使用@EnableSwagger2注解启用Swagger,并创建一个Docket bean来配置Swagger的一些参数。 以下是一个示例的Swagger配置类代码: ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.api")) .paths(PathSelectors.any()) .build(); } } ``` 在上述代码中,我们通过RequestHandlerSelectors.basePackage()方法指定了API接口所在的包路径,通过PathSelectors.any()方法指定了所有路径都被扫描。这样配置后,Swagger就可以扫描到我们想要展示的API接口。 最后,在启动类中添加@EnableSwagger2注解,启用Swagger。然后运行项目,访问Swagger UI界面(默认路径为:http://localhost:8080/swagger-ui.html),就可以看到API接口的文档、测试和调试信息了。 通过以上步骤,我们就成功地配置Swagger在Spring Boot项目中。使用Swagger可以方便地对API进行管理和测试,提高了开发效率。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值