SpringBoot 集成 Swagger

Swagger官网

什么是Swagger

  1. Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API
  2. Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现
  3. Swagger 文件可以在许多不同的平台上从代码注释中自动生成
  4. Swagger 有一个强大的社区

依赖导入

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

加入配置

swagger:
  title: 项目 API
  description: SpringBoot 集成 Swagger 项目 API
  version: 1.0
  terms-of-service-url: http://www.baidu.com/
  base-package: cn.anothertale.springbootshiro  # 这一项指定需要生成 API 的包,一般就是 Controller
  contact:
    name: taohan
    url: http://www.baidu.ccom/
    email: 1289747698@qq.com

建立 Swagger Config

package cn.anothertale.springbootshiro.config.swagger;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.context.properties.ConfigurationProperties;
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;

/**
 * description: swagger 配置中心
 *
 * @author: taohan
 * @date: 2019年03月20日
 * @time: 16:52
 */
@Getter
@Setter
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    /**
     * API 接口包路径
     */
    private String basePackage;

    /**
     * API 页面标题
     */
    private String title;

    /**
     * API 描述
     */
    private String description;

    /**
     * 服务条款地址
     */
    private String termsOfServiceUrl;

    /**
     * 版本号
     */
    private String version;

    /**
     * 联系人
     */
    private Contact contact;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact(contact)
                .build();
    }
}

通过注解标明 API

Swagger 默认根据配置的包,扫描所有接口并生成对应的 API 描述和参数信息。

常用注解及对应属性如下:

  • @Api (描述一个 API 类,标注在 Controller 上)

    1. value:url 的路径值
    2. tags:如果设置该值,value 的值会被覆盖
    3. description:API 的资源描述
    4. basePath:基本路径可以不设置
    5. produces:比如:application/json, application/xml 类似 RequestMapping 对应属性
    6. consumes:比如:application/json, application/xml
    7. authorizations:高级特性认证时配置
    8. hidden:是否在文档中隐藏
  • @ApiOperation (用在 Controller 方法上,说明方法的作用)
    1. value:url 的路径值
    2. tags:如果设置该值,value 的值会被覆盖
    3. description:对 API 资源的描述
    4. basePath:基本路径可以不设置
    5. position:如果配置多个 API 想改变展示位置,可通过该属性设置
    6. response:返回的对象
    7. responseContainer:这些对象是有效的 List、Set、Map,其他无效
    8. httpMethod:请求方式
    9. code:HTTP 状态码,默认200
    10. extensions:扩展属性
  • @ApiImplicitParams (用在 Controller 方法上,描述一组请求参数)
    1. value:ApiImplicitParam 数组,见下一注解
  • @ApiImplicitParam(描述一个请求参数)
    1. name:参数名称
    2. value:参数值
    3. defaultValue:参数默认值
    4. required:是否必须,默认 false
    5. access:不过多描述
    6. example:示例
  • @ApiResponses (描述一组响应)
    1. value:ApiResponse数组,见下一注解
  • @ApiResponse (描述一个响应)
    1. code:HTTP 的状态码
    2. message:描述消息

最后,可以在浏览器中输入 http://localhost:8080/swagger-ui.html 即可访问!

原文地址:https://www.cnblogs.com/dream-saddle/p/10566448.html

时间: 2024-11-05 18:33:16

SpringBoot 集成 Swagger的相关文章

SpringBoot集成Swagger,Postman,newman,jenkins自动化测试.

环境:Spring Boot,Swagger,gradle,Postman,newman,jenkins SpringBoot环境搭建. Swagger简介 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件. 一.SpringBoot集成Swagger 1.build.gradle增加swagger相关jar包,maven项目同理. 2.增加SwaggerConfig配置文件. 前两步完成,访问http://localhost:8080/demoService/swa

SpringBoot集成Swagger

Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 这里介绍一下spring boot和swagger基本的集成: 引入jar <!--Swagger--> <dependency> <groupId>io.springf

springboot 集成swagger

了解到swagger 就记录下用法 pom.xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</gr

Spring Boot 集成Swagger

Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 更多关于Swagger的作用,相信大家百度一下能了解的更全面,本文以SpringBoot中集成Swagger为例做介绍说明. 一.修改pom.xml,添加maven依赖 <!-- Swagger

springboot集成swagger2构建RESTful API文档

在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释 先介绍一下开发环境: jdk版本是1.8 springboot的版本是1.4.1 开发工具为 intellij idea 我们先引入swagger2的jar包,pom文件引入依赖如下: <dependency> <groupId>io.springfox&

(转) SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字. 一.引入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <vers

企业级 SpringBoot 教程 (十一)springboot集成swagger2,构建优雅的Restful API

swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字. 一.引入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <vers

JAVA springboot微服务b2b2c电子商务系统-springboot集成swagger2,构建优雅的Restful API(十一)

swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字. 一.引入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <vers

springboot之swagger快速启动

springboot之swagger快速启动 简介 介绍 可能大家都有用过swagger,可以通过ui页面显示接口信息,快速和前端进行联调. 没有接触的小伙伴可以参考官网文章进行了解下demo页面. 多应用 当然在单个应用大家可以配置SwaggerConfig类加载下buildDocket,就可以快速构建好swagger了. 代码大致如下: /** * Swagger2配置类 * 在与spring boot集成时,放在与Application.java同级的目录下. * 通过@Configura