Swagger2的简述与使用

#介绍

#springBoot+Swagger2

#SpringMVC+Swagger2

#生产环境的禁用

 

介绍

 

swagger是一个自动生成接口文档的工具，以往都是手写接口文档，难免不了许多出错的地方，swagger的出现大大地减少了开发人员处理这些琐碎时间，能让开发员专注于系统本身工作。swagger能自动生成restful风格的接口文档，并且支持在线测试，也能够为其他接口文档工具提供数据。下面介绍swagger的两种使用方式。

详情到官网https://swagger.io/

 

springBoot+swagger2

 

1,pom配置jar包

<!--引入swagger支持-->
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
 </dependency>
 <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
 </dependency>

      2,编写swagger配置代码

package com.wdk.config;

/**
 * @Author: DaiKang
 * @Description:
 * @Date: Created in 2020/1/22 20:45
 */

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //controller包位置
                .apis(RequestHandlerSelectors.basePackage("com.wdk.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口测试")
                .description("测试swagger")
                .version("1.0")
                .build();
    }
}

3，controller类里添加swagger处理

Controller
@Api("测试swagger接口")
@RequestMapping("/tests")
public class TestController {


    @ApiOperation(value ="增加接口",httpMethod = "PUT")
    @RequestMapping("/add")
    @ResponseBody
    public String add(){
        System.out.println("TestController.add");
        return "增加";
    }
    @ApiOperation(value = "删除接口",httpMethod = "DELETE")
    @RequestMapping("/delete")
    @ResponseBody
    public String delete(){
        return "删除";
    }
    @ApiOperation(value = "查询接口",httpMethod = "GET")
    @RequestMapping("/select")
    @ResponseBody
    public String select(){
        return "查询";
    }
    @ApiOperation(value = "修改接口",httpMethod = "POST")
    @RequestMapping("/update")
    @ResponseBody
    public String update(){
        return "修改";
    }

4，访问 http://localhost:8080/swagger-ui.html

 

springMVC+swagger2

 

1,maven添加jar包

<!--springfox依赖-->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-core</artifactId>
      <version>2.8.0</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.6.3</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-annotations</artifactId>
      <version>2.6.3</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
    </dependency>

2,编写swaggerConfig代码类

@Configuration
//@Profile({"dev","test"}) 测试与开发环境启用swagger
@EnableSwagger2
//@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 启用swagger
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.how2java.tmall.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("仿天猫项目(RESTFUL)风格API")
                .description("接口文档")
                .version("1.0")
                .build();
    }
}

3,controller类处理

 @ApiOperation(value = "分类删除接口",httpMethod = "DELETE")
    @RequestMapping("/admin_category_delete")
    public String  delete(Integer id,HttpSession session) throws IOException {
        if(null == id){
            id = 0;
        }
        System.out.println(id);
        categoryService.delete(id);
        File imageFolder = new File(session.getServletContext().getRealPath("img/category"));
        File file = new File(imageFolder,id+".jpg");
        file.delete();

        return "redirect:/admin_category_list";
    }

4，springmvc配置文件

         a，swagger默认首页swagger-ui.html

         b,SwaggerConfigl类配置成bean

 <!-- swagger静态文件路径 -->
    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
    <bean id="swaggerConfig" class="com.how2java.tmall.util.SwaggerConfig"/>

5，访问http://localhost:8080/swagger 测试：

 

 

 

生产环境的禁用

 

在开发和测试环境中可以运行swagger,但生产环境中，swagger接口文档过于暴露，生产环境禁用，测试环境开启。

@Configuration
//@Profile({"dev","test"}) 测试与开发环境启用swagger
@EnableSwagger2
//@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 启用swagger

1，使用@Profile注解，在生产环境自动禁用swagger，开发和测试环境自动开启。

2，使用SpringBoot下的@ConditionalOnProperty,禁用设置swagger.enable=true

 

完结！

 

如果觉得这篇文章对你有帮助的话，请点赞！