简单易懂的Swagger入门----idea版

超级简单入手的swagger教程

准备环境：

1. jdk----1.8
2. maven-----3.5
3. idea------2018

本次入门教程使用的是springboot结合maven，对swagger的简单入门教程，包括简单接口的编写、测试等；非常适合初学者。

一、创建springboot工程

1、创建工程

下面名称自己定义即可。

下面这里选择web-springWeb,有的版本就叫web

最后一步，直接finish即可。
2、配置maven环境
具体配置方法可以看一下我的上一篇：idea构建MaBtis逆向工程，其中有对maven环境的详细图解说明。
3、环境构建完成，我们来看一下我们搭建的springboot工程：

这里可以直接点击main方法的“小三角”，直接启动。

二、导入swagger依赖

1、导入我们需要的swagger依赖

这里我填上我的整个pom文件。注意红框圈起来的使我们需要的swagger依赖。

<?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 https://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.3.3.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.summer</groupId>
    <artifactId>swagger2_demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger2_demo</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>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <!--导入swagger版本，依赖-->
        <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>
    </dependencies>

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

</project>

2、接下来，就该编写我们的swagger配置核心类了。
情况一：
这里如果只是做一个启动demo，那么可以将此类的扫描包，直接写成：

然后，你可以直接启动springboot：

接着就可以直接在网页访问了：http://localhost:8080/swagger-ui.html#/

对比一下：

可以看到，已经swagger配置已经成功了，并且可以启动，浏览器直接访问。

情况二：
继续往下编写代码，完成完整的接口文档demo；此时，扫描包应该写这样写：

package com.summer.swagger2_demo.config;

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


/**
 * @program: swagger2-demo
 * @description: swagger2配置类
 * @author: Summer-DM
 * @create: 2020年08月26日
 **/
@Configuration
@EnableSwagger2
public class swagger2Config {

    @Bean
    public Docket buildDocket() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .apiInfo(apiInfo())//调用下面apiInfo()方法
                .select()
                //Controller所在路径
                .apis(RequestHandlerSelectors.basePackage("com.summer.swagger2_demo.web"))
                .paths(PathSelectors.any())
                .build();

    }

    public ApiInfo apiInfo() {
        Contact contact = new Contact("Summer-DM","https://blog.csdn.net/yy_wzh","62******7@qq.com");
        return  new ApiInfoBuilder()
                .title("springboot结合swagger2构建Restful API") //标题
                .description("This is a swagger2 demo!") //描述(小标题)
                .termsOfServiceUrl("www.baidu.com") //网站链接
                .contact(contact) //链接显示的文字
                .version("0.0.1") //版本
                .build();

    }
}

3、编写model包的实体类，这里测试User；

package com.summer.swagger2_demo.Model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;
/**
 *@program: swagger2-demo
 *  * @description: 用户测试类
 *  * @author: Summer-DM
 *  * @create: 2020年08月26日
 *
 *  用到注解说明：
 *     @ApiModel：用于类 ；表示对类进行说明，用于参数用实体类接收
 *              value–表示对象名
 *              description–描述
 *              都可省略
 *     @ApiModelProperty：用于方法，字段； 表示对model属性的说明或者数据操作更改
 *              value–字段说明
 *              name–重写属性名字
 *              dataType–重写属性类型
 *              required–是否必填
 *              example–举例说明
 *              hidden–隐藏
 *              都可省略
 */

//@ApiModel("用户信息类")
@ApiModel(value="user对象",description="用户对象user类")
public class User  implements Serializable{
    @ApiModelProperty(value="用户id",name="id",example="100",required=true)
    private Long id;
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private String age;
    @ApiModelProperty("性别")
    private String sex;
    @ApiModelProperty("地址")
    private String addr;
    @ApiModelProperty("手机号")
    private String phone;
    @ApiModelProperty("邮箱")
    private String email;
    @ApiModelProperty("身份证")
    private String idCard;
    @ApiModelProperty("健康")
    private String health;

    public User() {
    }

    public User(Long id, String name, String age, String sex, String addr) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.sex = sex;
        this.addr = addr;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name == null ? null : name.trim();
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age == null ? null : age.trim();
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex == null ? null : sex.trim();
    }

    public String getAddr() {
        return addr;
    }

    public void setAddr(String addr) {
        this.addr = addr == null ? null : addr.trim();
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone == null ? null : phone.trim();
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email == null ? null : email.trim();
    }

    public String getIdCard() {
        return idCard;
    }

    public void setIdCard(String idCard) {
        this.idCard = idCard == null ? null : idCard.trim();
    }

    public String getHealth() {
        return health;
    }

    public void setHealth(String health) {
        this.health = health == null ? null : health.trim();
    }
}

4、编写controller类；

5、启动服务

6、浏览器访问地址：http://localhost:8080/swagger-ui.html

以上就是我们的整个swagger配置，启动等过程，代码方面已经编写完毕，接下来，我们可以去测试一下。

三、测试

测试一个post请求的demo，创建用户：


可以看到返回请求200，并且有response body返回。

我在idea上打了断点，可以看到创建用户成功。
因为我只是配置了数据库，但是并没有编写连接、操作的代码，所以只能在页面上看到接口通了。

swagger官网：https://swagger.io/

以上只是swagger的初步使用，仅适合于初学者入门，因为本人也是初学者，在网上找了很多不同的入门教程，综合起来，自己亲自跑了一遍，这是自己跑下来的流程，初学者入门应该足够了，如果大佬看到，写的有问题的地方还请指正。