Swagger2

最新推荐文章于 2023-08-14 14:44:18 发布

strggle_bin

最新推荐文章于 2023-08-14 14:44:18 发布

阅读量130

点赞数

分类专栏： springboot

本文链接：https://blog.csdn.net/strggle_bin/article/details/109490900

版权

springboot 专栏收录该内容

9 篇文章 0 订阅

订阅专栏

集成Swagger2

引入pom依赖

	<!--swagger2-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>${swagger2.version}</version>
	</dependency>
	<!--swagger2-ui-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger2.version}</version>
    </dependency>
    <!--swagger-bootstrap-ui-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>${swagger.bootstrap.version}</version>
    </dependency>

开启注解

在启动类中开启@EnableSwagger2注解

package com.example.swagger2;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class Swagger2Application {
	public static void main(String[] args) {
		SpringApplication.run(Swagger2Application.class, args);
	}
}

配置基本信息

创建Swagger2Config配置类，并填充对应平台信息

package com.bonc.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.web.bind.annotation.RestController;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @date 2020-03-09
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {

    /**
     * 文件描述
     */
    @Value("${common.swagger.code.description:xxxx管理系统}")
    private String codeDescription;
    /**
     * 邮箱
     */
    @Value("${common.swagger.code.email:xxx@xxx.com.cn}")
    private String codeEmail;
    /**
     * 作者名称
     */
    @Value("${common.swagger.code.author:xxx}")
    private String codeName;
    /**
     * 文档标题
     */
    @Value("${common.swagger.code.title:xxx管理系统RESTful API}")
    private String codeTitle;
    /**
     * 作者Url
     */
    @Value("${common.swagger.code.url:https://www.xxxx.com.cn//}")
    private String codeUrl;
    /**
     * 版本
     */
    @Value("${common.swagger.code.version:1.0.0}")
    private String codeVersion;
    /**
     * 服务Url
     */
    @Value("${common.swagger.code.service.url:https://www.xxx.com.cn/}")
    private String serviceUrl;
    /**
     * 开启swagger
     */
    @Value("${common.swagger.code.enable:true}")
    private boolean enableSwagger;

    /**
     * 创建Api
     *
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>();
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }

    /**
     * 初始化ApiInfo
     *
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(codeTitle)
                .description(codeDescription)
                .termsOfServiceUrl(serviceUrl)
                .version(codeVersion)
                .contact(new Contact(codeName, codeUrl, codeEmail))
                .build();
    }
}

编写控制器

package com.example.swagger2.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

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

@Controller
public class TestController {
    @GetMapping("/test")
    @ResponseBody
    public Map<String, Object> getMsg() {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "response msg");
        return map;
    }
}

访问API界面

启动服务后，访问地址http://ip:port/swagger-ui.html，即可见swagger主页
或http://ip:port/项目名称/doc.html

常用配置

自定义响应消息

Swagger 允许我们通过 Docket 的 globalResponseMessage() 方法全局覆盖 HTTP 方法的响应消息，但是首先我们得通过 Docket 的 useDefaultResponseMessages 方法告诉 Swagger 不使用默认的 HTTP 响应消息，假设我们现在需要覆盖所有 GET 方法的 500 和 403 错误的响应消息，我们只需要在 SwaggerConfig.java 类中的 Docket Bean 下添加如下内容：

扫描包路径设置

只扫描com.example.swagger2.controller路径下的方法

 @Bean
 public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(swaggerDemoApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.swagger2.controller"))
            .build();
    }

设置不需要生成接口文档的方法（自定义注解）

定义一个方法级别的注解，策略为运行时解析

package com.example.swagger2.config;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

(not(withMethodAnnotation(NotIncludeSwagger.class)))表示方法级别注解不执行

...
import static com.google.common.base.Predicates.not;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger2.controller"))
                .apis((not(withMethodAnnotation(NotIncludeSwagger.class))))
                .build();
    }

 ....

在对应方法上使用@NotIncludeSwagger即可，该方法不会显示在swagger接口文档页面

	@NotIncludeSwagger
    @GetMapping("/test")
    @ResponseBody
    public Map<String, Object> getMsg() {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "response msg");
        return map;
    }

设置范围

使用paths()方法，可以通过正则方式指定需要匹配到的方法；
定义2个方法，分别以/test和/hello访问路径开头

	@GetMapping("/test/getMsg")
    @ResponseBody
    public Map<String, Object> getMsg() {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "response msg");
        return map;
    }

    @PostMapping("/hello/getMsg2")
    @ResponseBody
    public Map<String, Object> getMsg2() {
        Map<String, Object> map = new HashMap<>();
        map.put("result", "response msg");
        return map;
    }

指定访问所有/test路径开头的方法

...
 .apis((not(withMethodAnnotation(NotIncludeSwagger.class))))
                .paths(PathSelectors.regex("/test/.*"))
                .build();

指定多个时使用or方法

.paths(or(PathSelectors.regex("/test/.*"), PathSelectors.regex("/hello/.*")))

三、常用注解

@Api

@Api 是类上注解，通过在控制器类上增加@Api 注解，可以给控制器增加描述和标签信息。
主要属性

注解属性	类型	描述
tags	String[]	控制器标签（类的名称。可以有多个值，多个值表示多个副本）。
description	String	控制器描述（该字段被申明为过期）。

@Api(tags = {"类名称信息"},description = "类描述信息")
public class TestController {}

@ApiOperation

@ApiOperation 写在方法上，通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述。
主要属性

注解属性	类型	描述
value	String	接口说明。
notes	String	接口发布说明。
tags	String[]	标签。
response	Class<?>	接口返回类型。
httpMethod	String	接口请求方式。

	@ApiOperation(value="接口描述",notes = "接口提示信息")
    @PostMapping("/test/getMovieInfo")
    @ResponseBody
    public MovieInfo getMovieInfo() {
        MovieInfo info = new MovieInfo();
        info.setName("当幸福来敲门");
        info.setRole("威尔史密斯");
        return info;
    }

@ApiParam

@ApiParam 写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明；

注解属性	类型	描述
name	String	参数名称。
value	String	参数描述。
required	String	是否必传字段。

public MovieInfo getMovieInfo(@ApiParam(value="电影名称",required = true) String name) {}

@ApiModel

@ApiModel 是类上注解，主要应用 Model，也就是说这个注解一般都是写在实体类上；
value：实体对象名称；
description：实体对象描述信息；

@ApiModel(value = "电影实体对象",description = "电影实体对象描述")
public class MovieInfo {

    private Long id;    //主键
    private String name;    //电影名称
    private String role;    //主演
    private String area;    //地区（大陆、香港、美国）
	...
}

@ApiModelProperty

@ApiModelProperty 可以用在方法或属性上。可设置实体属性的相关描述；
value：String，字段说明。
name：String 重写字段名称。
dataType：Stirng 重写字段类型。
required：boolean 是否必填。
example：Stirng 举例说明。
hidden：boolean 是否在文档中隐藏该字段。
allowEmptyValue：boolean 是否允许为空。
allowableValues：String 该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。

	@ApiModelProperty(value = "电影名称",name = "name",required = true, example = "当幸福来敲门")
    private String name;    //电影名称

@ApiIgnore

@ApiIgnore 用于方法或类或参数上，表示这个方法或类被忽略，和上面自定义的@NotIncludeSwagger 注解功能相似；

@ApiIgnore
public boolean delete(@PathVariable("id") int id)

@ApiImplicitParam

@ApiImplicitParam 用在方法上，表示单独的请求参数，总体功能和@ApiParam 类似；
name：属性名；
value：描述；
required：是否必填。取值：true：必填参数。false：非必填参数。
dataType：参数的数据类型。取值：Long，String
paramType：查询参数类型，实际上就是参数放在那里。取值：path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。query：Query string 的方式传参。header：以流的形式提交。form：以 Form 表单的形式提交。

	@ApiImplicitParam(name = "name",value = "电影名称",required = true,paramType = "query",dataType = "string")
    public MovieInfo getMovieInfo( String name) {}