SwaggerUI+SpringBoot

最新推荐文章于 2023-09-03 22:39:44 发布

老书G

最新推荐文章于 2023-09-03 22:39:44 发布

阅读量680

点赞数

CC 4.0 BY-SA版权

分类专栏： java 文章标签： swagger api 规范

本文链接：https://blog.youkuaiyun.com/arttecme/article/details/83022721

java 专栏收录该内容

5 篇文章

订阅专栏

本文提供了一套SpringBoot项目中集成Swagger2的最新、精简教程，包括配置依赖、编写配置类、添加注解及模型注释，帮助快速实现API文档自动生成。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

网上能搜索到的教程版本大多数要么太老了，要么就是行不通，所以在这里整理一个新版的可用的精简的说明。

完整演示代码

step1：pom.xml 增加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

step2：创建SwaggerUI的配置类：

package com.gefork.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gefork.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://localhost:8080/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("演示抬头")
                .description("一些描述")
                .termsOfServiceUrl("http://code.gefork.com/service")
                .version("1.0")
                .contact(new Contact("小卖部作家", "http://www.gefork.com", "1583590390@qq.com"))
                .build();
    }
}

step3：在对应的controller中添加注解（以@Api开头的那些注解）。

package com.gefork.controller;

import com.gefork.entity.UserEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

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

@Api(tags="用户接口模块")
@Controller
@EnableAutoConfiguration
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value="打个招呼", notes = "你可以发送一些消息，然后你会得到一个text/plain的回复。", httpMethod = "GET")
    @ApiImplicitParam(paramType="query", name = "message", value = "消息内容", example = "HelloWorld", required = true, dataType = "String")
    // http://localhost:8080/user/get_query?message=HelloWorld
    @RequestMapping(value = "/get_query", produces = "text/plain;charset=UTF-8")
    @ResponseBody
    String get_query(@RequestParam String message) {
        return "你说的是:\n" + message;
    }

    @ApiOperation(value="查询生日", notes = "访问你想查询的用户，然后你会得到一个text/plain的生日。", httpMethod = "GET")
    @ApiImplicitParam(paramType="path", name = "username", value = "用户名", example = "admin", required = true, dataType = "String")
    // http://localhost:8080/user/path_query/admin
    @RequestMapping(value = "/path_query/{username}", produces = "text/plain;charset=UTF-8")
    @ResponseBody
    String path_query(@PathVariable String username) {
        return username + "的生日是1949-10-01";
    }

    @ApiOperation(value="新增用户", notes = "创建一个系统的新用户。")
    @ApiImplicitParams({
            // 即使使用 paramType="form" 也无法支持以表单形式进行传参，
            // 因此使用 paramType="query" 作为替代方案。
        @ApiImplicitParam(paramType="query", name = "username", value = "用户名", example = "admin", required = true, dataType = "String"),
        @ApiImplicitParam(paramType="query", name = "password", value = "密码", example = "123", required = true, dataType = "int")
    })
    // http://localhost:8080/user/post_form_1
    @RequestMapping(value = "/post_form_1", produces = "application/json;charset=UTF-8", method = RequestMethod.POST)
    @ResponseBody
    Map<String, Object> post_form_1(@RequestParam String username, @RequestParam Integer password) {
        Map<String, Object> result = new HashMap<>();
        result.put("username", username);
        result.put("password", password);
        result.put("message", "创建成功");
        return result;
    }


    @ApiOperation(value="新增完整用户", notes = "创建一个系统的新用户,并支持更多的信息。")
    // http://localhost:8080/user/post_form_2
    @RequestMapping(value = "/post_form_2", produces = "application/json;charset=UTF-8", method = RequestMethod.POST)
    @ResponseBody
    UserEntity post_form_2(UserEntity user) {
        return user;
    }

    @ApiOperation(value="新增完整用户(有效荷载方式)", notes = "创建一个系统的新用户,并支持更多的信息。")
    // http://localhost:8080/user/post_payload
    @RequestMapping(value = "/post_payload", produces = "application/json;charset=UTF-8", method = RequestMethod.POST)
    @ResponseBody
    UserEntity post_payload(@RequestBody  UserEntity user) {
        return user;
    }
}

step4：还能为对应的model增加注释

package com.gefork.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.springframework.format.annotation.DateTimeFormat;

import java.util.Date;
import java.util.List;

@ApiModel("用户信息")
public class UserEntity {

    @ApiModelProperty(value = "用户名", example = "gefork")
    private String username;

    @ApiModelProperty(value = "密码", example = "123456")
    private Integer password;

    @ApiModelProperty(value = "生日", example = "1988-09-11")
    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date birthday;

    @ApiModelProperty("房产信息")
    private HouseEntity house;

    @ApiModelProperty("拥有的会员卡")
    private List<CardEntity> cards;

    // 在此省略 Getter & Setter
}

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