Swagger之学习使用

前言

这个是为了介绍一下Swagger的使用，最近也在使用Swagger，就在下面这篇文章介绍下，我特地改了上次分享的外卖项目，添加了Swagger注解…

添加依赖

Maven项目添加依赖

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

Spring Boot添加项目依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Swagger 项目的配置文件

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

Spring boot项目需要添加配置项到你的Swagger配置类上***@EnableSwagger2WebMvc***

@Configuration
@EnableSwagger2WebMvc
public class SpringFoxConfig {                                    
}

如果不是Spring boot的话，就不能自动配置好请求的路径，其他项目就需要添加Swagger的静态资源的配置路径映射，这个资源映射我们需要添加

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

添加Swagger-UI，Swagger-UI可以帮助你查看接口文档和测试，我们需要添加一个依赖

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

我们可以通过浏览器去访问它

http://localhost:8080/your-app-root/swagger-ui/

相关注解

使用Swagger注解是服务于前后端分类开发，更加方便我们和前端进行对接，那接口文档是怎么样可以生成呢，前面我们只是搭建了接口查看的地址，那这些接口时怎么扫描进去的呢，下面我将列举一些常用到的注解出来以及怎么使用。

注解	说明
@ApiModel(value =“地址信息”)	这个value是对接口的描述，一般我们对将这个注解加在Controller上。
@ApiOperation(value = “新增地址”)	这个注解是添加在方法上，是用于方法描述，tags是用来进行分组，produces是指定返回内容类型，consumes时指定提交处理请求的内容类型
@ApiParam(value = “地址信息”, required = true)	参数说明，value是参数描述，而required是否为必填项，
@ApiModel(“菜品”)	对象实体类的说明，value是实体的说明
@ApiModelProperty(“菜品id”)	value类的字段说明，required表示是否为必填项，hidden是隐藏

上述就是我们比较常用的注解，通过这些注解我们可以在运行我们的项目时，通过访问路径就可以访问接口文档，这样在对前后端进行分离开发时也会更加方便，而且一般接口文档都可以支出导出多种形式，下面是我项目的接口文档接口，项目的介绍也有下面这个链接，我使用的是一个依赖，但是对请求路径映射也是需要配置的。

项目地址:

<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
 </dependency>