快捷導(dǎo)航

springboot項目配置swagger2示例詳解

更新時間：2021年09月16日 10:14:03 作者：小志的博客

Swagger是一款RESTful接口的文檔在線自動生成、功能測試功能框架。本文重點給大家介紹springboot項目配置swagger2示例代碼詳解，需要的朋友參考下吧

swagger簡介

　　Swagger是一款RESTful接口的文檔在線自動生成、功能測試功能框架。一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)，加上swagger-ui，可以有很好的呈現(xiàn)。

　　當(dāng)我們在后臺的接口修改了后，swagger可以實現(xiàn)自動的更新，而不需要人為的維護這個接口進行測試。

一、swagger2中常用的注解作用

注解	作用
@Api	修飾整個類，描述Controller的作用，表示標(biāo)識這個類是swagger的資源
@ApiOperation	描述一個類的一個方法，或者說一個接口，表示一個http請求的操作
@ApiParam	用于方法的參數(shù)，表示對參數(shù)的添加元數(shù)據(jù)
@ApiModelProperty	用于方法，字段。表示對model屬性的說明或者數(shù)據(jù)操作更改

二、springboot項目配置swagger2步驟

1、springboot項目的目錄結(jié)構(gòu)如下：

在這里插入圖片描述

2、pom.xml文件引入如下配置

<!--引入web相關(guān)依賴-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引入swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--引入swagger-ui-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>

3、application.yml配置文件配置如下

server:
  port: 8001 #端口
  servlet:
    context-path: /springSecurity #配置項目名稱

4、Swagger配置文件如下：

package com.xz.springsecuritydemo.config;

import com.google.common.base.Predicate;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

/**
 * @description: Swagger配置文件
 * @author: xz
 */
@Configuration
@EnableSwagger2//開啟Swagger2
public class SwaggerConfig {

    //注入配置文件中的項目名稱
    @Value("${server.servlet.context-path}")
    private String contextPath;

    /**
     * 構(gòu)建 swagger2 api 文檔的詳細(xì)信息函數(shù)
     * @return
     */
    private ApiInfo initApiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("springSecurity測試項目 Platform API")//大標(biāo)題
                .version( "1.0.0")//版本
                .description(initContextInfo())//描述
                .contact(new Contact("xz", "https://wwwxz.blog.csdn.net/", "123456@qq.com"))//作者信息
                .license("The System Server, Version 1.0")//網(wǎng)站鏈接顯示文字
                .licenseUrl("https://wwwxz.blog.csdn.net/")//網(wǎng)站鏈接
                .build();

        return apiInfo;
    }

    private String initContextInfo() {
        StringBuffer sb = new StringBuffer();
        sb.append("REST API 設(shè)計在細(xì)節(jié)上有很多自己獨特的需要注意的技巧，并且對開發(fā)人員在構(gòu)架設(shè)計能力上比傳統(tǒng) API 有著更高的要求。")
                .append("<br/>")
                .append("本文通過翔實的敘述和一系列的范例，從整體結(jié)構(gòu)，到局部細(xì)節(jié)，分析和解讀了為了提高易用性和高效性，REST API 設(shè)計應(yīng)該注意哪些問題以及如何解決這些問題。");

        return sb.toString();
    }

    /**
     * swagger2的配置文件，這里可以配置swagger2的一些基本的內(nèi)容，比如掃描的包等等
     * @return
     */
    @Bean
    public Docket restfulApi() {
        System.out.println("http://localhost:8001" + contextPath + "/swagger-ui.html");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(initApiInfo())
                .groupName("RestfulApi")
                //.genericModelSubstitutes(DeferredResult.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .pathMapping(contextPath) // base，最終調(diào)用接口后會和paths拼接在一起
                .select()
                 //加了ApiOperation注解的類，才生成接口文檔
                 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                 //暴露接口地址的包路徑（即此包下的類，才生成接口文檔）
                .apis(RequestHandlerSelectors.basePackage("com.xz.springsecuritydemo.modules.sys.controller"))
                .paths(doFilteringRules())//自定義的過濾規(guī)則
                .build();
    }

    /**
     * 設(shè)置過濾規(guī)則
     * 這里的過濾規(guī)則支持正則匹配
     * @return
     */
    private Predicate<String> doFilteringRules() {
        return or(
                regex("/testUser.*"),
                regex("/hello.*")
        );
    }
}

5、用戶實體類如下：

package com.xz.springsecuritydemo.modules.sys.entity;

import io.swagger.annotations.ApiModelProperty;
/**
 * @description: 用戶實體類
 * @author: xz
 */
public class UserQueryCondition {
    private int id;
    @ApiModelProperty(value = "用戶名稱")
    private String name;
    private int age;

    public int getId() {
        return id;
    }

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

    public String getName() {
        return name;
    }

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

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

6、控制層代碼如下：

package com.xz.springsecuritydemo.modules.sys.controller;

import com.xz.springsecuritydemo.modules.sys.entity.User;
import com.xz.springsecuritydemo.modules.sys.entity.UserQueryCondition;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang.builder.ReflectionToStringBuilder;
import org.apache.commons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.*;
/**
 * @description: 控制層代碼如下
 * @author: xz
 */
@Api(value = "API - UserController",description = "用戶模塊接口詳情")
@RestController
@RequestMapping("/testUser")
public class UserController {

    /***
     *  @ApiParam 如果方法接受的是具體參數(shù)，此注解需要加到方法中的參數(shù)上
     */
    @RequestMapping(value = "/queryUserByName",method = RequestMethod.GET)
    @ApiOperation(value = "根據(jù)用戶名稱查詢服務(wù)")
    public void queryUserByName(@ApiParam(value = "用戶username") @RequestParam(name="username",required = false, defaultValue ="tom" ) String name){
        System.out.println("queryUser====="+name);
    }

    /***
     * @ApiOperation 可用在方法頭上.參數(shù)的描述容器
     * @ApiModelProperty 如果方法接受的是實體，此注解需要加到實體的具體屬性上
     */
    @RequestMapping(value = "/queryUserAll",method = RequestMethod.GET)
    @ApiOperation(value = "根據(jù)用戶id、名稱和年齡查詢服務(wù)")
    public void queryUserAll(UserQueryCondition userQueryCondition){
        //利用反射工具把對象輸出
        System.out.println(ReflectionToStringBuilder.toString(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE));
    }

    /***
     * @ApiOperation 可用在方法頭上.參數(shù)的描述容器
     */
    @PostMapping(value = "/createUser")
    @ApiOperation(value = "用戶新增服務(wù)")
    public User userCreate1(@RequestBody User user){
        System.out.println(user.getName()+"----"+user.getPassword());
        user.setId(1);
        return user;
    }

    /***
     * @ApiOperation 可用在方法頭上.參數(shù)的描述容器
     */
    @PutMapping("/{id:\\d+}")
    @ApiOperation(value = "用戶修改服務(wù)")
    public User update(@RequestBody User user){
        System.out.println(user.getId()+"======"+user.getName()+"----"+user.getPassword());
        user.setId(1);
        return user;
    }

    /***
     * @ApiOperation 可用在方法頭上.參數(shù)的描述容器
     */
    @DeleteMapping("/{id:\\d+}")
    @ApiOperation(value = "用戶刪除服務(wù)")
    public void delete(@PathVariable String id){
        System.out.println(id);
    }
}

7、啟動項目，如下圖：

在這里插入圖片描述