SpringBoot整合swagger

最新推荐文章于 2024-07-31 09:32:30 发布

敏捷践行者

最新推荐文章于 2024-07-31 09:32:30 发布

阅读量261

点赞数

分类专栏：读书笔记文章标签： spring boot spring java swagger

本文链接：https://blog.csdn.net/yebichao/article/details/129310557

版权

读书笔记专栏收录该内容

87 篇文章 1 订阅

订阅专栏

本文介绍了如何在SpringBoot项目中集成Swagger，通过引入相关依赖、编写配置类和测试控制器，来创建和展示RESTfulAPI的文档。Swagger提供了方便的API接口描述、测试和交互功能。

摘要由CSDN通过智能技术生成

SpringBoot整合swagger

**
1、引入maven

<?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>
    <modules>
        <module>springboot-test</module>
        <module>swagger</module>
    </modules>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.5</version>
    </parent>

    <groupId>org.bc</groupId>
    <artifactId>springboot-study</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <jackson.version>2.10.0</jackson.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.12</version>
            <scope>test</scope>
        </dependency>
        <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>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>${jackson.version}</version>
        </dependency>

    </dependencies>
    <build>
        <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
            <plugins>
                <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <version>3.1.0</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

</project>

<?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-study</artifactId>
        <groupId>org.bc</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>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>
    <dependency>
        <groupId>commons-lang</groupId>
        <artifactId>commons-lang</artifactId>
        <version>2.6</version>
    </dependency>

</dependencies>

2、编写配置类

package org.bc.swagger;

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 SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();

    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().build();
    }
}

3、编程测试类

package org.bc.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.bc.swagger.domain.Result;
import org.bc.swagger.domain.User;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

/**
 *
 * 用户管理
 *
 */
@Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("user")
public class UserController {

    // 列出某个类目的所有规格
    @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "list", method = RequestMethod.GET)
    public Result<User> list(
            @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
            @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
            @ApiParam(value = "token", required = true) @RequestParam String token) {
        Result<User> result = new Result<User>();
        User user = new User();
        user.setName("zhangsan");
        user.setPassword("password");
        user.setSex(1);
        user.setToken("aastewetwewe97wewesf7w8");
        result.setData(user);
        return result;
    }

    @RequestMapping(value = "getUserById", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "根据id获得用户信息", notes = "用户信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
    public User getUserById(
            @ApiParam(value = "user ID", required = true) @RequestParam String id
    ){
        User user = new User();
        user.setName("lisi");
        user.setPassword("password");
        user.setSex(1);
        user.setToken("aastewetwewe97wewesf7w8");
        return user;
    }

    @ApiOperation(value = "添加用户", notes = "添加用户(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "add", method = RequestMethod.POST)
    // @RequestBody只能有1个
    // 使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
    // 只能手动调用方法
    public Result<String> add(@RequestBody User user) {
        String u = findUser(user);
        System.out.println(u);
        return null;
    }

    @ApiOperation(value = "update用户", notes = "update user", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "update", method = RequestMethod.GET)
    public Result<String> update(User user) {
        String u = findUser(user);
        System.out.println(u);
        return null;
    }

    private String findUser(User user) {
        String token = user.getToken();
        return token;
    }
}

4、编写启动类

package org.bc.swagger;

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

@SpringBootApplication
public class SwaggerApp {
    public static void main(String args[]){
        System.out.println("test....");
        SpringApplication.run(SwaggerApp.class);
    }
}

在这里插入图片描述

5、说明
注解浏览
@Api : 在类上注解表名这个类是一个Swagger资源
@ApiImplicitParam 在API Operation中代表只有一个参数
@ApiImplicitParams 包装多个ApiImplicitParam对象
@ApiModel 关于Swagger模块提供额外的信息
@ApiModelProperty 添加和操作模型属性数据
@ApiOperation 描述一个操作或者通常针对特定路径的HTTP方法
@ApiParam 添加操作参数的额外元数据
@ApiResponse 描述一个操作可能的响应
@ApiResponses 包装多个ApiResponse对象
@Authorization声明对一个资源或者操作的授权
@AuthorizationScope 声明OAuth2授权范围
@ResponseHeader声明可以作为response的头部

详情请见：
http://jakubstas.com/spring-jersey-swagger-create-documentation/