SpringBoot集成Swagger2

1、简介

首先谈谈什么是Web API

 如果我们把前端页面看作是一种用于展示的客户端，那么API就是为客户端提供数据、操作数据的接口。例如我们可以通过访问http://localhost:8080/getName?id=2来获取用户id=2的名字。

 

REST就是一种设计API的模式,它的主要原则有：

** 网络上的所有事物都被抽象为资源**

** 每个资源都有一个唯一的资源标识符**

** 同一个资源具有多种表现形式(xml,json等)**

** 对资源的各种操作不会改变资源标识符**

** 所有的操作都是无状态的**

** 符合REST原则的架构方式即可称为RESTful**

2、SpringBoot 集成Swagger2

     Swagger2可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

    首先添加依赖

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

 然后添加Swagger2配置项：

package com.example.demo.config;

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.service.ApiKey;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public Docket buildDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(buildApiInf())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
                .title("系统RESTful API文档")
                .version("1.0")
                .build();
    }


}

  最后在Controller层进行配置就行，访问http://localhost:8080/swagger-ui.html即可以得到界面。有关操作方法我写在了注释里面

package com.example.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

//http://localhost:8080/swagger-ui.html
@Api(value = "Controller") //修饰整个类
@Controller
@RequestMapping("/h1")
public class ControllerDemo {

    //@ApiIgnore //忽略该请求
    //描述一个类的一个方法，或者说一个接口；
    @ApiOperation(value = "输出信息",notes="注释")
    @RequestMapping("/h11")
    @ResponseBody
    public String fun(){
        return "hello";
    }


    @DeleteMapping("/id")
    @ApiOperation(value = "多个参数请求")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户Id",dataType = "int",required = true,paramType = "query"),
            @ApiImplicitParam(name = "name",value = "用户名字",dataType = "String",required = true)
    })
    /*
    *header-->请求参数的获取：@RequestHeader(代码中接收注解)
    query-->请求参数的获取：@RequestParam(代码中接收注解)
    path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
    body-->请求参数的获取：@RequestBody(代码中接收注解)*/
    public String fun2(@RequestParam("id") String id, @RequestParam("name") String name){
     return "id:"+id+"name:"+name;
    }


}

注：上面的第二个参数name，我忘记加paraType了，它的值也应该是query，不加他会默认为body的，如下面的图，还有用@RequestMapping时，尽量指定method,或者使用GepMapper,PutMapper,DeleteMapping等等，不然他会把生成多个使用不同方法的API，。

 

还有没用到的注释先写在下面,以防后面会使用到。

@ApiParam：单个参数描述；

@ApiModel：用对象来接收参数；

@ApiProperty：用对象接收参数时，描述对象的一个字段；

@ApiResponse：HTTP响应其中1个描述；

@ApiResponses：HTTP响应整体描述；

@ApiIgnore：使用该注解忽略这个API；

@ApiError ：发生错误返回的信息；