Swagger的使用

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

swagger 介绍及两种使用方法

方法一：使用第三方依赖（最简单的方法）

1、在pom.xml文件中添加第三方swagger依赖（）

	<dependency>
		<groupId>com.spring4all</groupId>
		<artifactId>swagger-spring-boot-starter</artifactId>
		<version>1.7.0.RELEASE</version>
	</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目，里面有详细的讲解。

方法二：使用官方依赖

1、在pom.xml文件中添加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>

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

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 Swagger2 {
　　　　　/** 
　　　　　　* 通过createRestApi函数创建Docket的Bean之后， 
　　　　　　* apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中） 
　　　　　　* select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现， 
　　　　　　* apis()函数扫描所有Controller中定义的API， 并产生文档内容（除了被@ApiIgnore指定的请求） 
　　　　　　* @return 
　　　　　　*/
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                    .paths(PathSelectors.any())
                    .build();
        }
　　　　　/**
　　　　　　* 创建该Api的基本信息（这些基本信息会展现在文档页面中） 
　　　　　　* @return 
　　　　　　*/
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台 APIs")
                    .description("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台")
                    .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin")
                    .contact("程序猿")
                    .version("1.0")
                    .build();
        }

    }

 

 

三、具体使用

1、在API上做一些声明

//本controller的功能描述
@Api(value = "pet", description = "the pet API")
public interface PetApi {

    //option的value的内容是这个method的描述，notes是详细描述，response是最终返回的json model。其他可以忽略
    @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = {
        @Authorization(value = "petstore_auth", scopes = {
            @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
            @AuthorizationScope(scope = "read:pets", description = "read your pets")
            })
    }, tags={ "pet", })

    //这里是显示你可能返回的http状态，以及原因。比如404 not found, 303 see other
    @ApiResponses(value = { 
        @ApiResponse(code = 405, message = "Invalid input", response = Void.class) })
    @RequestMapping(value = "/pet",
        produces = { "application/xml", "application/json" }, 
        consumes = { "application/json", "application/xml" },
        method = RequestMethod.POST)
    ResponseEntity<Void> addPet(
    //这里是针对每个参数的描述
    @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);

2、设定访问API doc的路由

在配置文件中，application.yml中声明：

springfox.documentation.swagger.v2.path: /api-docs

这个path就是json的访问request mapping.可以自定义，防止与自身代码冲突。

API doc的显示路由是：http://localhost:8080/swagger-ui.html

如果项目是一个webservice，通常设定home / 指向这里：

@Controller
public class HomeController {

    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

四：swagger的常用API

1、api标记

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

 

 

2、ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

Swagger常用注解

 

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

 

主要属性如下：

 

 实例

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {

}

2、@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性：

 

 实例

 

@RequestMapping(value = "/order/{orderId}", method = GET)
  @ApiOperation(
      value = "Find purchase order by ID",
      notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
      response = Order.class,
      tags = { "Pet Store" })
   public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }

3、@ApiOperation

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性：

 

 实例

public ResponseEntity<Order> getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)

3、@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam也可以定义参数.

• @ApiImplicitParams：用在请求的方法上，包含一组参数说明
• @ApiImplicitParam：对单个参数的说明

主要属性：

 

 实例：

@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/login")
    public JsonResult login(@RequestParam String mobile, @RequestParam String password,
    @RequestParam Integer age){
        //...
        return JsonResult.ok(map);
    }

4、@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

主要属性：

 

 

实例：

@ApiResponses({
        @ApiResponse(code = 200, message = "请求成功"),
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    }) 
    @ResponseBody
    @RequestMapping("/list")
    public JsonResult list(@RequestParam String userId) {
        ...
        return JsonResult.ok().put("page", pageUtil);
    }

5、@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性。

实例：

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{

    @ApiModelProperty(value = "是否成功",required=true)
    private boolean success=true;    
    
    @ApiModelProperty(value = "错误码")
    private Integer errCode;
    
    @ApiModelProperty(value = "提示信息")
    private String message;
    
    @ApiModelProperty(value = "数据")
    private Object data;
        
    /* getter/setter 略*/
}

6、 @PathVariable

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

实例：

@GetMapping("/query/{id}")
    private List<Student> queryById( @ApiParam(name = "id", value = "学生id", required = true) @PathVariable("id") Long id) {
        List<Student> studentList = studentService.queryById(id);
        return studentList;
    }

7、 @RequestParam

@RequestParam用于获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数。

实例：

@GetMapping("/query/student")
    private List<Student> queryByIdStu( @ApiParam(name = "byId", value = "学生id", required = false) @RequestParam("id") Long id) {
        List<Student> studentList = studentService.queryById(id);
        return studentList;
    }