SpringBoot整合Swagger2

• 前言

现在都奉行前后端分离开发和微服务大行其道，分微服务及前后端分离后，前后端开发的沟通成本就增加了。所以一款强大的RESTful API文档就至关重要了。而目前在后端领域，基本上是Swagger的天下了。

• Swagger2介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

• SpringBoot集成

• 配置pom文件

  <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>
  

• 创建SwaggerProperties

  @Data
  @ConfigurationProperties(prefix = "swagger")
  public class SwaggerProperties {
      private String title;
      private String description;
      private String version;
      private String license;
      private String licenseUrl;
      private String contactName;
      private String contactUrl;
      private String contactEmail;
  }
  

• 创建BootAdminCoreConfig

  @Configuration
  @EnableConfigurationProperties({SwaggerProperties.class})
  public class BootAdminCoreConfig {
  }
  

• 配置application.yml

  swagger:
      title: "Boot Admin API"
      description: "Boot Admin 接口文档说明"
      version: "2.0"
      license: "Apache License 2.0"
      licenseUrl: "http://www.apache.org/licenses/LICENSE-2.0"
      contactName: "boot admin"
      contactUrl: "http://blog.qiuyd.com"
      contactEmail: "abelethan@126.com"
  

• 创建Swagger2Config

  @Configuration
  @EnableSwagger2
  public class Swagger2Config {
  
      @Autowired
      private SwaggerProperties swagger;
  
      @Bean
      public Docket createRestApi(){
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                  .paths(PathSelectors.any())
                  .build();
      }
  
      private ApiInfo apiInfo(){
          return new ApiInfoBuilder()
                  .title(swagger.getTitle())
                  .description(swagger.getDescription())
                  .license(swagger.getLicense())
                  .licenseUrl(swagger.getLicenseUrl())
                  .contact(new Contact(swagger.getContactName(), swagger.getContactUrl(), swagger.getContactEmail()))
                  .version(swagger.getVersion())
                  .build();
      }
  }
  

• 接口配置

  @Api(value = "用户API", tags = {"用户操作接口"})
  public interface UsersApi {
  
      /**
       * 获取用户信息
       *
       * @return
       */
      @ApiOperation(value = "获取用户信息", notes = "用户详细信息，附带角色信息，权限信息", httpMethod = "GET")
      @GetMapping("/info")
      Wrapper<UserInfoDTO> getInfo();
  
      /**
       * 获取用户信息 分页查询
       *
       * @param query
       * @return
       */
      @ApiOperation(value = "获取用户信息 分页查询", notes = "用户信息分页查询", httpMethod = "GET")
      @ApiImplicitParam(name = "query", value = "用户信息查询条件", required = true, dataType = "UserVoQuery")
      @GetMapping("/page")
      Wrapper<UserVoQuery> pageByQuery(UserVoQuery query);
  
      /**
       * 增加用户信息 带绑定信息
       *
       * @param userVO
       * @return
       */
      @ApiOperation(value = "增加用户信息", notes = "增加用户信息 待绑定信息", httpMethod = "POST")
      @ApiImplicitParam(name = "userVO", value = "用户信息", required = true, dataType = "UserVO")
      @PostMapping
      Wrapper<Boolean> save(@RequestBody UserVO userVO);
  
      /**
       * 修改用户信息 待绑定信息
       *
       * @param userVO
       * @return
       */
      @ApiOperation(value = "修改用户信息", notes = "修改用户信息 待绑定信息", httpMethod = "PUT")
      @ApiImplicitParam(name = "userVO", value = "用户信息", required = true, dataType = "UserVO")
      @PutMapping
      Wrapper<Boolean> update(@RequestBody UserVO userVO);
  
      /**
       * 删除用户信息
       *
       * @param id
       * @return
       */
      @ApiOperation(value = "删除用户信息", notes = "删除用户信息", httpMethod = "DELETE")
      @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
      @DeleteMapping("/id/{id}")
      Wrapper<Boolean> delete(@PathVariable("id") Long id);
  
      /**
       * 主键查询用户信息
       *
       * @param id
       * @return
       */
      @ApiOperation(value = "主键查询用户信息", notes = "查询用户信息", httpMethod = "GET")
      @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
      @GetMapping("/id/{id}")
      Wrapper<Users> get(@PathVariable("id") Long id);
  }
  

• Swagger访问与使用

  api首页路径：http://127.0.0.1:8080/swagger-ui.html
  
  调试：点击需要访问的api列表，点击try it out!按钮，即可弹出一下页面：
  
  执行
  

常用的注解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有进行标注，对于其他注解，大家可自动谷歌。
其它相关的操作可自行查看官网文档

• 总结

本文主要是对Swagger的集成和简单使用进行了说明，详细的用法，可自行搜索相关资料下，这里就不阐述了。最后，强烈建议在生产环境关闭swagger,避免不必要的漏洞暴露！