Swagger 介绍

Swagger UI 允许任何人(无论是开发团队还是最终用户)都可以可视化 API 资源并与之交互,而无需任何实现逻辑。

Swagger API 文档是根据 OpenAPI(以前称为 Swagger)规范自动生成的,可简化后端实现和客户端的使用。

Swagger 依赖

        <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-bean-validators</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>

SpringBoot 集成 Swagger 配置类

package com.example.apitestplatform.config;

import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
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; /**
* Swagger 文档配置类
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig { @Bean
public Docket docket() {
ParameterBuilder builder=new ParameterBuilder();
builder.parameterType("header")
.name("token")
.description("token值")
.required(true)
.modelRef(new ModelRef("string")); // 在swagger文档里展示header return new Docket(DocumentationType.SWAGGER_2)
.groupName("ApiDemo")
.apiInfo(apiInfo())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select() // 选择生成策略
.apis(RequestHandlerSelectors.basePackage("com.example.apitestplatform.controller")) // 选择生成文档的类(忽略该行则不做过滤)
.paths(PathSelectors.any())
.build();
} // 定义接口文档基本信息
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("ApiDemo 系统") // 接口文档标题
.description("ApiDemo 接口文档") // 接口文档描述
.contact(new Contact("xiaoming", "", "103@qq.com")) // 作者联系方式
.version("1.0") // 接口文档版本
.build();
}
}

常用注解

  • @Api(tags="API 类标题")
  • @ApiOperation(value="API 方法标题")
  • @ApiModel(value="实体类标题", description="实体类描述")
  • @ApiModelProperty(value="实体属性描述",example="属性示例取值", required=true)

示例:

  • 接口类:
package com.example.apitestplatform.controller;

import com.example.apitestplatform.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*; @Api(tags="Swagger Demo 类")
@RestController
@RequestMapping(value="demo") // 类中所有接口地址的前缀
public class DemoController { @Value("${user.hobby}")
private String hobby; @ApiOperation(value="Swagger Demo get方法")
// @RequestMapping(value="loginGet", method= RequestMethod.GET)
@GetMapping("loginGet")
public String loginGet() {
return hobby;
} // @RequestMapping(value="loginPost", method= RequestMethod.POST)
@PostMapping("loginPost") // 简便写法
public String loginPost(@RequestBody User user) { // 如果没用 @RequestBody,则获取结果为 null
System.out.println("username : "+user.getUsername());
System.out.println("password : "+user.getPassword());
return "登录成功:"+user.getUsername();
} // 访问:http://localhost:8080/demo/userId/1/2
// @RequestMapping(value="userId/{userId}/{id}", method=RequestMethod.GET)
@GetMapping("getUser/{userid}/{id}")
public String loginUser1(@PathVariable("userid") Integer userid, @PathVariable("id") Integer id) {
System.out.println("userid : "+userid);
System.out.println("id : "+id);
return "userid: "+userid+" id: "+id;
} // 访问:http://localhost:8080/demo/getUser?userid=1&id=2
// 访问:http://localhost:8080/demo/getUser?user=1&id=2,则 userid 值为 null
@GetMapping("getUser")
public String loginUser2(@RequestParam(value="userid", required=false) Integer userid, // required=false:参数非必须传
@RequestParam("id") Integer id) {
System.out.println("userid : "+userid);
System.out.println("id : "+id);
return "userid: "+userid+" id: "+id;
}
}
  • User 类
package com.example.apitestplatform.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data; @ApiModel(value="用户类", description="用户信息")
@Data
public class User { @ApiModelProperty(value="用户名", example="xiaoming", required=true)
private String username;
@ApiModelProperty(value="密码", example="123456", required=true)
private String password;
}

效果示例

Swagger 接口文档的更多相关文章

  1. springboot+swagger接口文档企业实践(下)

    目录 1.引言 2. swagger接口过滤 2.1 按包过滤(package) 2.2 按类注解过滤 2.3 按方法注解过滤 2.4 按分组过滤 2.4.1 定义注解ApiVersion 2.4.2 ...

  2. SpringBoot开发mockserver及生成swagger接口文档

    通过springboot开发mock server,包含get及post接口,用于练习接口自动化及jmeter很方便 当然,也为后面jenkins持续集成做基础(开发push代码后  → jenkin ...

  3. .net core的Swagger接口文档使用教程(二):NSwag

    上一篇介绍了Swashbuckle ,地址:.net core的Swagger接口文档使用教程(一):Swashbuckle 讲的东西还挺多,怎奈微软还推荐了一个NSwag,那就继续写吧! 但是和Sw ...

  4. .Net Core---- WebApi生成Swagger接口文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  5. REST-framework快速构建API--生成Swagger接口文档

    一.Swagger概述 1.引言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次接口有变更,需要手动修改 ...

  6. swagger接口文档

    1 在Visual Studio 中创建一个Asp.NET  WebApi 项目,项目名:Com.App.SysApi(本例创建的是 .net 4.5 框架程序) 2  打开Nuget 包管理软件,查 ...

  7. springboot+swagger接口文档企业实践(上)

    目录 1.引言 2.swagger简介 2.1 swagger 介绍 2.2 springfox.swagger与springboot 3. 使用springboot+swagger构建接口文档 3. ...

  8. Swagger 接口文档规范

    导语: 相信无论是前端还是后端开发,都或多或少地被接口文档折磨过.前端经常抱怨后端给的接口文档与实际情况不一致.后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新.其实无论是前端调用后端,还是 ...

  9. .netcore 3.1高性能微服务架构:加入swagger接口文档

    本文为原创文章:首发:http://www.zyiz.net/tech/detail-108663.html swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视 ...

  10. Core3.0使用Swagger接口文档

    前言 此方法为百度搜索结果,原文链接找不到了 步骤 1.引用Nuget Swashbuckle.AspNetCore 2.Startup.cs配置 //注册swagger服务,定义1个或者多个swag ...

随机推荐

  1. HOOK API(四) —— 进程防终止

    0x00        前言 这算是一个实战吧,做的一个应用需要实现进程的防终止保护,查了相关资料后决定用HOOK API的方式实现.起初学习HOOK API的起因是因为要实现对剪切板的监控,后来面对 ...

  2. NSString为何要用copy修饰,而不是strong?

    NSString本身是无所谓的,但是如果一个 NSString 指针指向了一个 NSMutableString的内存空间的话,如果使用 strong 修饰的话,如果你在别处修改这个值的话,那么原来的值 ...

  3. 实例15_C语言绘制万年历

    实例说明:

  4. java程序出现oom如何解决?什么场景下会出现oom?

    1.什么是oom? OOM,全称"Out Of Memory",翻译成中文就是"内存用完了",来源于java.lang.OutOfMemoryError. 当J ...

  5. SYSTEM表空间满,解决方法

    SYSTEM表空间是Oracle创建数据库时候自动创建的,每个Oracle数据库都会有SYSTEM表空间,而且SYSTEM表空间总是要保持在联机模式下,因为其包含了数据库运行所要求的基本信息,如:数据 ...

  6. 关于es update异常 ScriptException[dynamic scripting for [groovy] disabled]

    你需要在elasticsearch.yml中配置 script.disable_dynamic: false 然后别忘了重启.

  7. Solution -「ABC 213H」Stroll

    \(\mathcal{Description}\)   Link.   给定一个含 \(n\) 个结点 \(m\) 条边的简单无向图,每条边的边权是一个常数项为 \(0\) 的 \(T\) 次多项式, ...

  8. 图计算 on nLive:Nebula 的图计算实践

    本文首发于 Nebula Graph Community 公众号 在 #图计算 on nLive# 直播活动中,来自 Nebula 研发团队的 nebula-plato 维护者郝彤和 nebula-a ...

  9. Windows微信清理工具v.3.0.1

    Windows微信清理工具v.3.0.1 今天,我原创的Windows微信清理工具迎来最大更新! v.3.0.0更新内容: 1.使用tkinter重构GUI,界面更简单易用! 2.增加"清理 ...

  10. head 插件 Content-Type header [application/x-www-form-urlencoded] is not supported

    { "error": "Content-Type header [application/x-www-form-urlencoded] is not supported& ...