什么是Swagger
- Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成
- 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 上)
- value:url 的路径值
- tags:如果设置该值,value 的值会被覆盖
- description:API 的资源描述
- basePath:基本路径可以不设置
- produces:比如:application/json, application/xml 类似 RequestMapping 对应属性
- consumes:比如:application/json, application/xml
- authorizations:高级特性认证时配置
- hidden:是否在文档中隐藏
- @ApiOperation (用在 Controller 方法上,说明方法的作用)
- value:url 的路径值
- tags:如果设置该值,value 的值会被覆盖
- description:对 API 资源的描述
- basePath:基本路径可以不设置
- position:如果配置多个 API 想改变展示位置,可通过该属性设置
- response:返回的对象
- responseContainer:这些对象是有效的 List、Set、Map,其他无效
- httpMethod:请求方式
- code:HTTP 状态码,默认200
- extensions:扩展属性
- @ApiImplicitParams (用在 Controller 方法上,描述一组请求参数)
- value:ApiImplicitParam 数组,见下一注解
- @ApiImplicitParam(描述一个请求参数)
- name:参数名称
- value:参数值
- defaultValue:参数默认值
- required:是否必须,默认 false
- access:不过多描述
- example:示例
- @ApiResponses (描述一组响应)
- value:ApiResponse数组,见下一注解
- @ApiResponse (描述一个响应)
- code:HTTP 的状态码
- message:描述消息
最后,可以在浏览器中输入 http://localhost:8080/swagger-ui.html 即可访问!
原文地址:https://www.cnblogs.com/dream-saddle/p/10566448.html
时间: 2024-11-05 18:33:16