【六袆-Swagger】SpringBoot集成Swagger（它是一套基于OpenAPI规范构建的开源工具，可以帮助我们设计、构建、记录以及使用Rest API）案例篇

Swagger优势：给我们提供了一个全新的维护API文档的方式

 

 

一、创建springboot工程

       可以通过Spring Initializr页面生成一个空的Spring Boot项目，当然也可以下载springboot-pom.xml文件，然后使用Maven构建一个Spring Boot项目。项目创建完成后，为了方便后面代码的编写您可以将其导入到您喜欢的IDE中，使用工具Intelli IDEA打开 

 

二、依赖pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.3.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>com.xiaolonghong</groupId>
    <artifactId>Swaggerdemo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <name>Swaggerdemo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <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>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

 

三、编写接口

1.创建三个包：cn.xiaolonghong.sbswagger.controller、cn.xiaolonghong.sbswagger.testcontroller、cn.xiaolonghong.sbswagger.model

2.在controller新建UserController.java类，testcontroller包下新建TestController.java类，在model包新建User.java类

UserController.java

注明L:提供用户的增、删、查、改、四个接口

package cn.xiaolonghong.sbswagger.controller;

import cn.xiaolonghong.sbswagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

/**
   1. 浏览器访问swagger-ui效果： http://localhost:8080/swagger-ui.html
   2. 在Spring Boot项目中集成了Swagger2，启动项目后，
      我们可以通过在浏览器中访问  http://localhost:8080/v2/api-docs 来验证，
      你会发现返回的结果是一段JSON串，可读性非常差。



    @ApiIgnore: Swagger文档不会显示拥有该注解的接口。
    @ApiImplicitParams: 用于描述接口的非对象参数集。
    @ApiImplicitParam: 用于描述接口的非对象参数，一般与@ApiImplicitParams组合使用。
    @ApiOperation: 可设置对接口的描述。
    注解属性	类型	描述
    value	String	接口说明。
    notes	String	接口发布说明。
    tags	Stirng[]	标签。
    response	Class<?>	接口返回类型。
    httpMethod	String	接口请求方式。

     注解属性	描述
     paramType	查询参数类型，实际上就是参数放在那里。取值： path：以地址的形式提交数据，根据id查询用户的接口就是这种形式传参。 query：Query string的方式传参。 header：以流的形式提交。 form：以Form表单的形式提交。
     dataType	参数的数据类型。取值：Long，String
     name	参数名字。
     value	参数意义的描述。
     required	是否必填。取值：true：必填参数，false：非必填参数。


   注明：springboot-集成swagger教程及配置： https://itweknow.cn/blog-site/posts/2111459879.html
 */
@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
public class UserController {




    @ApiOperation("更新用户信息接口")
    @PutMapping("/update")
    public boolean update(@RequestBody User user) {
        return true;
    }

    @ApiOperation("删除用户接口")
    @DeleteMapping("/delete/{id}")
    @ApiIgnore
    public boolean delete(@PathVariable("id") int id) {
        return true;
    }

    @ApiOperation("新增用户接口")
    @PostMapping("add")
    public boolean addUser(@RequestBody User user){
        return false;
    }

    @ApiOperation("通过id查找用户接口")
    @GetMapping("/find/{id}")
    public User findById(@PathVariable("id") int id) {
        return new User();
    }
}

TestController.java

注明：提供一个测试接口

package cn.xiaolonghong.sbswagger.testcontroller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 提供一个测试接口
 */
@RestController
@RequestMapping("test")
@Api(tags = "测试相关接口", description = "提供测试相关的Rest API")
public class TestController {

    @GetMapping("/test")
    public void test(){
        System.out.println("test");
    }
}

User.java

package cn.xiaolonghong.sbswagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/*
  接口相关注解
  @ApiModel: 可设置接口相关实体的描述。
  @ApiModelProperty: 可设置实体属性的相关描述。
    注解属性	        类型	  描述
     value	            String	  字段说明。
     name	            String	  重写字段名称。
     dataType	        Stirng	  重写字段类型。
     required	        boolean	  是否必填。
     example	        Stirng	  举例说明。
     hidden	            boolean	  是否在文档中隐藏该字段。
     allowEmptyValue    boolean	  是否允许为空。
     allowableValues	String	  该字段允许的值，当我们API的某个参数为枚举类型时，使用这个属性就可以清楚地告诉API使用者该参数所能允许传入的值。
 */

@ApiModel("用户实体")
public class User {
        /**
         * 用户Id
         */
        @ApiModelProperty("用户id")
        private int id;

        /**
         * 用户名
         */
        @ApiModelProperty("用户姓名")
        private String name;


        /**
         * 用户地址
         */
        @ApiModelProperty("用户地址")
        private String address;

        public int getId() {
            return id;
        }

        public User setId(int id) {
            this.id = id;
            return this;
        }

        public String getName() {
            return name;
        }

        public User setName(String name) {
            this.name = name;
            return this;
        }

        public String getAddress() {
            return address;
        }

        public User setAddress(String address) {
            this.address = address;
            return this;
        }
    }

 

四、自定义响应信息

在config包下新建SwaggerConfig.java

package cn.xiaolonghong.sbswagger.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
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;

import java.util.Collections;

import static com.google.common.collect.Lists.newArrayList;

/**
 * @Configuration 告诉Spring Boot需要加载这个配置类
 * @EnableSwagger2   启用Swagger2，如果没加的话自然而然也就看不到后面的验证效果
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.xiaolonghong.sbswagger.controller"))
                .paths(Predicates.or(PathSelectors.ant("/user/add"),
                        PathSelectors.ant("/user/find/*")))
                .build()
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, newArrayList(
                        new ResponseMessageBuilder()
                                .code(500)
                                .message("服务器发生异常")
                                .responseModel(new ModelRef("Error"))
                                .build(),
                        new ResponseMessageBuilder()
                                .code(403)
                                .message("资源不可用")
                                .build()
                ));
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "Spring Boot项目集成Swagger实例文档",
                "我的CSDN博客网站：https://blog.csdn.net/qq_41086359，欢迎大家访问。",
                "API V1.0",
                "Luyi of service",
                new Contact("lIUYI", "https://blog.csdn.net/qq_41086359", "[email protected]"),
                "Apache", "http://www.apache.org/", Collections.emptyList());
    }
}

 

 五、编写一个启动类

App.java

package cn.xiaolonghong.sbswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }
}

 

六、浏览器访问

1. 浏览器访问swagger-ui效果： http://localhost:8080/swagger-ui.html

2. 在Spring Boot项目中集成了Swagger2，启动项目后，
   我们可以通过在浏览器中访问  http://localhost:8080/v2/api-docs 来验证，
   你会发现返回的结果是一段JSON串，可读性非常差。

 效果图