Spring Boot集成Swagger快速入门Demo

news2024/11/26 22:40:24

1.什么是Swagger？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

主要作用：

使得前后端分离开发更加方便，有利于团队协作。（实际开发中，接口文档的内容会不停的发生变化，如果没有及时更新接口文档，那么前后端就不能及时同步信息。我们通过在线的接口文档swagger，这样前后端工程师都遵守swagger就行了，只要接口文档发生了变化，就会实时更新。）
接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger

2.代码工程

实验目的：接口的文档在线自动生成

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">
    <parent>
        <artifactId>springboot-demo</artifactId>
        <groupId>com.et</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>


    <artifactId>swagger</artifactId>


    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>
    <dependencies>


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


        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</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-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>


    </dependencies>
</project>

config

package com.et.swagger.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 java.util.Collections;


@Configuration
public class SwaggerConfiguration {
    private ApiInfo apiInfo() {
        return new ApiInfo("Blog REST APIs",
                "REST APIs for Blog Application",
                "1.0",
                "http://www.liuhaihua.cn",
                new Contact("HBLOG", "http://www.liuhaihua.cn", "xxx"),
                "License of API",
                "API license URL",
                Collections.emptyList());
    }
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

controller

package com.et.swagger.controller;


import com.et.swagger.model.LoginDto;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;


import java.util.HashMap;
import java.util.Map;


@RestController
@Api(value = "HelloWorldController", tags = "HelloWorldController", description = "this is a test")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation("showHelloWorld")
    public Map<String, Object> showHelloWorld(){
        Map<String, Object> map = new HashMap<>();
        map.put("msg", "HelloWorld");
        LoginDto loginDto =  new LoginDto();
        loginDto.setPassword("123456");
        loginDto.setPhone("11111123123");
        map.put("loginuser", loginDto);
        return map;
    }
    @PostMapping("/login_auth")
    @ApiOperation("login")
    public LoginDto login(@RequestBody LoginDto loginDto){
        return loginDto;
    }
}

model

package com.et.swagger.model;


import io.swagger.annotations.ApiModelProperty;
import lombok.Data;


@Data
public class LoginDto {
    @ApiModelProperty(value = "phone",required = true)
    private String phone;
    @ApiModelProperty(value = "password",required = true)
    private String password;
}

以上只是一些关键代码，所有代码请参见下面代码仓库