Swagger的配置及使用教程

Swagger的配置及使用教程

1.简介。
在项目开发的过程中 ,一个好的API开发文档是必不可少的,开发文档有助于前后端用户的沟通交流，减少沟通成本，由于之前的开发文档存在一些问题，比如接口多、细节复杂、API接口不能实时更新等等，就导致了Swagger2的诞生，它完美的解决了这个问题，它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
2.使用。
1.我们用springboot来使用一下swagger吧，首先新建一个springboot项目。

2. 选中web模块即可，等会儿要在浏览器做测试。

3.完成之后，我们需要引入我们引入swagger的依赖。这里需要用到两个依赖，一个springfox-swagger2，一个springfox-swagger-ui

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

4.依赖导入之后，我们要写一个配置类来开启Swagger2，配置类里面可以什么都不写，用默认的，也可以自定义配置。我们先什么都不写，先看看默认的情况，再来自定义配置。
配置类：

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    

}

这里的两个注解，一个@Configuration，表明这是一个注解类，@EnableSwagger2注解就表示开启Swagger2。完成好了之后，我们启动测试一下。
在浏览器输入网址：http://localhost:8080/swagger-ui.html 。注意这里访问的是swagger-ui.html页面，这里swagger里的默认页面，以后的请求接口都在这个页面。

可以点开这个接口看一下，有很多请求方式，当我们用了restfui方式的请求形式，这里就只会有一种方式了。我们来写几个接口测试下。

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/test")
public class HelloController {
    
    

    @GetMapping("one")
     public String one(){
    
    
         return  "one";
     }

    @PostMapping("two")
    public String two(){
    
    
        return  "two";
    }

    @DeleteMapping("three")
    public String three(){
    
    
        return  "three";
    }

    @GetMapping("add/{a}/{b}")
    public int add(@PathVariable int a ,
                     @PathVariable int b){
    
    
        return  a+b;
    }
}

注意这里的注解是@RestController。
我们还是打开http://localhost:8080/swagger-ui.html

点击打开。

这里就是我们写的4个测试接口，我们来测试一下，就测试这个加法吧。



这样，接口就测试成功了。

3.自定义配置Swagger
加下来，我们来自定义配置一下Swagger，让它更加人性化吧。
打开刚刚写的Swagger配置类。我们还什么都没配置呢。

import com.google.common.base.Predicates;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
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 webApiConfig(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                //调用apiInfo方法,创建一个ApiInfo实例,
                // 里面是展示在文档页面信息内容
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }


    // api文档的详细信息
    private ApiInfo webApiInfo(){
    
    

        return new ApiInfoBuilder()
                .title("API文档接口测试")    //标题
                .description("本文档描述接口测试用例")  //描述
                .version("1.0")  //版本
                .contact(new Contact("java", "http://baidu.com", "[email protected]"))
                .build();
    }
}

写完了这些配置，我们先来看下效果

在配置类中就是配置相应的位置，让api文档更清晰。

4.一些注解的使用
除了使用自定义配置外，我们还可以使用注解让文档接口更加清晰。
我们来改造下Controller

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/test")
//说明该类的作用
@Api(tags = "一些测试用例")
public class HelloController {
    
    

    @GetMapping("one")
    @ApiOperation(value = "one方法，返回数据",notes = "这里可以写一些详细信息")
     public String one(){
    
    
         return  "one";
     }

    @PostMapping("two")
    @ApiOperation(value = "two方法，返回数据",notes = "这里可以写一些详细信息")
    public String two(){
    
    
        return  "two";
    }

    @DeleteMapping("three")
    @ApiOperation(value = "three方法，返回数据",notes = "这里可以写一些详细信息")
    public String three(){
    
    
        return  "three";
    }

    @GetMapping("add/{a}/{b}")
    @ApiOperation(value = "add方法，返回数据",notes = "这里可以写一些详细信息")
    public int add(@ApiParam(value = "参数a", required = true) @PathVariable int a ,
                   @ApiParam(value = "参数b", required = true)  @PathVariable int b){
    
    
        return  a+b;
    }
}

先看效果：

注解说明：
1.@Api
@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源，使用方式代码如下所示。

@Api(tags={
    
    "用户接口"})
@RestController
public class UserController {
    
    
}

2.ApiParam
@ApiParam 用于 Controller 中方法的参数说明。使用方式代码如下所示。

@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
    
    
    System.err.println(param.getName());
    return new UserDto();
}

3.ApiOperation
@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。使用方式代码如下所示

@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {
    
    

}

4.ApiModel
@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

@ApiModel(value = "com.znzz.user", description = "新增用户参数")
public class AddUserParam {
    
    
}

5.ApiModelProperty
@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示。

@Data
@ApiModel(value = "com.znzz.user", description = "新增用户参数")
public class AddUserParam {
    
    
    @ApiModelProperty(value = "ID")
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}