SpringBoot集成Swagger文档

短命女 2024-04-17 06:46 62阅读 0赞

## Swagger ##

### 1 介绍 ###

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务([https://swagger.io/][https_swagger.io])。 它的主要作用是：

1.  使得前后端分离开发更加方便，有利于团队协作
2.  接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
3.  功能测试
    
    Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

目前，一般都使用knife4j框架。

#### 2 使用步骤 ####

1.  导入 knife4j 的maven坐标
    
    在pom.xml中添加依赖
    
        <dependency>
           <groupId>com.github.xiaoymin</groupId>
           <artifactId>knife4j-spring-boot-starter</artifactId>
           		<version>3.0.2</version>
        </dependency>
2.  在配置类中加入 knife4j 相关配置
    
    SwaggerConfig .java

@Configuration
    @Slf4j
    public class SwaggerConfig extends WebMvcConfigurationSupport {
        
        /**
         * 通过knife4j生成接口文档
         * @return
         */
        @Bean
        public Docket docket() {
        
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("智慧社区项目接口文档")
                    .version("1.0")
                    .description("智慧社区项目接口文档")
                    .build();
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .groupName("管理端")
                    .apiInfo(apiInfo)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.bs.bszhsq.controller"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
    
        /**
         * 设置静态资源映射
         * @param registry
         */
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        
            registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

1.  设置静态资源映射，否则接口文档页面无法访问
    
    SwaggerConfig .java
    
        /**
             * 设置静态资源映射
             * @param registry
        */
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
              
                registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
                registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
2.  访问测试
    
    接口文档访问路径为 http://ip:port/doc.html —> 例子：http://localhost:8080/doc.html

### 3 常用注解 ###

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

<table> 
 <thead> 
  <tr> 
   <th><strong>注解</strong></th> 
   <th><strong>说明</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api</td> 
   <td>用在类上，例如Controller，表示对类的说明</td> 
  </tr> 
  <tr> 
   <td>@ApiModel</td> 
   <td>用在类上，例如entity、DTO、VO</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty</td> 
   <td>用在属性上，描述属性信息</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation</td> 
   <td>用在方法上，例如Controller的方法，说明方法的用途、作用</td> 
  </tr> 
 </tbody> 
</table>

**后记  
????美好的一天，到此结束，下次继续努力！欲知后续，请看下回分解，写作不易，感谢大家的支持！！ ???**

[https_swagger.io]: https://swagger.io/