swagger接口规范说明

WebApi接⼝测试⼯具：Swagger前⾔：WebApi接⼝开发完毕后，交付给前端⼈员或⼿机端开发者时接⼝说明⽂档是必不可少的配套设备，如果公司流程不规范⼤家使⽤⼝⼝相传的交接⽅式，⽽且没有改进的欲望，那你可以到此为⽌了。

Swagger是⽅便测试接⼝，快速展⽰注释内容，⽣成Restful风格接⼝⽂档的框架。

⼀、Swagger介绍Swagger能成为最受欢迎的REST APIs⽂档⽣成⼯具之⼀，有以下⼏个原因：Swagger 可以⽣成⼀个具有互动性的API控制台，开发者可以⽤来快速学习和尝试API。

Swagger 可以⽣成客户端SDK代码⽤于各种不同的平台上的实现。

Swagger ⽂件可以在许多不同的平台上从代码注释中⾃动⽣成。

Swagger 有⼀个强⼤的社区，⾥⾯有许多强悍的贡献者。

按照下述步骤操作，你就能在WebApi中使⽤Swagger，本⽂做测试⽤的版本v5.6.0，好好看吧，如果有可改进的地⽅，欢迎⼤家留⾔。

⼆、Swagger展⽰第⼀印象：接⼝列表。

点击某⼀个接⼝查看接⼝详细点击Try it out三、Swagger的使⽤1、如何引⼊组件⾸先，我们需要定义⼀个API项⽬然后通过Nuget引⼊组件，如下图2、如何使⽤组件1、打开解决⽅案属性-->⽣成，勾选XML⽂档⽂件，保存就ok。

2、SwaggerNet类中，注释类上⾯的两⾏3、如果运⾏出现以下错误，则更改配置⽂件web.config出现该异常是由于没有增加依赖项，⼤家可以⾃⾏查看⾃⼰的dll⽂件版本，做出修改，把下⾯的代码插⼊到web.config中。

<dependentAssembly><assemblyIdentity name=".Http.Formatting" publicKeyToken="31bf3856ad364e35" culture="neutral"/><bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0"/></dependentAssembly><dependentAssembly><assemblyIdentity name="System.Web.Http" publicKeyToken="31bf3856ad364e35" culture="neutral"/><bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0"/></dependentAssembly><dependentAssembly><assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral"/><bindingRedirect oldVersion="0.0.0.0-8.0.0.0" newVersion="8.0.0.0"/>3、测试接⼝为了⽅便测试我们新建⼀个App的Model///<summary>/// App信息///</summary>public class App{///<summary>/// App的ID号///</summary>public int Id { get; set; }///<summary>/// App的名称///</summary>public string Name { get; set; }///<summary>/// App的说明///</summary>public string Remark { get; set; }}返回消息ResultJson的Model///<summary>///返回处理结果///</summary>public class ResultJson{///<summary>///返回代码///</summary>public int Code { get; set; }///<summary>///返回消息///</summary>public string Message { get; set; }}public class AppController : ApiController{private List<App> GetApps(){List<App> list = new List<App>();list.Add(new App() { Id = 1, Name = "WeChat", Remark = "WeChat" });list.Add(new App() { Id = 2, Name = "FaceBook", Remark = "FaceBook" }); list.Add(new App() { Id = 3, Name = "Google", Remark = "Google" });list.Add(new App() { Id = 4, Name = "QQ", Remark = "QQ" });return list;}///<summary>///获取所有APP///</summary>///<returns>所有APP集合</returns>[HttpGet]public HttpResponseMessage Get(){return MyJson.ObjectToJson(GetApps());}///<summary>///获取指定APP///</summary>///<param name="id">需要获取APP的id</param>///<returns>返回指定APP</returns>[HttpGet]public HttpResponseMessage Get(int id){var app = GetApps().Where(m => m.Id.Equals(id)).FirstOrDefault();return MyJson.ObjectToJson(app);}///<summary>///增加App信息///</summary>///<param name="value"></param>///<returns></returns>[HttpPost]public HttpResponseMessage Insert([FromBody]App value){ResultJson json = new ResultJson() { Code = 200, Message = "Ok" };return MyJson.ObjectToJson(json);}///<summary>///更新APP信息///</summary>///<param name="value">APP信息</param>///<returns>更新结果</returns>[HttpPut]public HttpResponseMessage UpdateApp([FromBody]App value){ResultJson json = new ResultJson() { Code = 200, Message = "Ok" };return MyJson.ObjectToJson(json);}///<summary>///删除APP信息///</summary>///<param name="id">APP编号</param>///<returns>删除结果</returns>[HttpDelete]public HttpResponseMessage DeleteApp(int id){ResultJson json = new ResultJson() { Code = 200, Message = "Ok" };return MyJson.ObjectToJson(json);}}好了我们运⾏后可以看看效果点击 Try it out我们还可以将注释打开，我们就可以在页⾯⾥⾯看到注释，⽅便调试接⼝时候调⽤⼈了解各参数信息。

swagger注释API详细说明转载：https:///xupeng874395012/article/details/68946676链接：https:///p/12f4394462d5API详细说明注释汇总作⽤范围API使⽤位置对象属性@ApiModelProperty⽤在出⼊参数对象的字段上协议集描述@Api⽤于controller类上协议描述@ApiOperation⽤在controller的⽅法上Response集@ApiResponses⽤在controller的⽅法上Response@ApiResponse⽤在 @ApiResponses⾥边⾮对象参数集@ApiImplicitParams⽤在controller的⽅法上⾮对象参数描述@ApiImplicitParam⽤在@ApiImplicitParams的⽅法⾥边描述返回对象的意义@ApiModel⽤在返回对象类上作⽤在 controller 层：/** Controller 层* 取消发布*/@PostMapping("/exitpub")@ApiOperation(value = "图书取消发布",produces = "application/json", consumes="application/json")@RequiresPermissions("cms:bookresource:publish")@ApiImplicitParam(name="ids",allowMultiple = true,value = "id数组",required=true,paramType = "body",dataType="Long")public R unpublish(@PathVariable("ids") String[] ids){作⽤在实体层 entity@ApiModelProperty("编辑")@TableField(exist = false)private List<EditorEntity> editorList = new ArrayList<>();@ApiImplicitParam属性取值作⽤paramType查询参数类型path以地址的形式提交数据query直接跟参数完成⾃动映射赋值body以流的形式提交仅⽀持POSTheader参数在request headers ⾥边提交form以form表单的形式提交仅⽀持POSTdataType参数的数据类型只作为标志说明，并没有实际验证LongStringname接收参数名value接收参数的意义描述required参数是否必填true必填false⾮必填defaultValue默认值@ApiImplicitParam(name = "id",value = "资源id",required=false,paramType = "path",dataType="Long")paramType ⽰例详解path@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)@PathVariable(name = "id") Long idbody@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })@RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE) @RequestBody MessageParam param提交的参数是这个对象的⼀个json，然后会⾃动解析到对应的字段上去，也可以通过流的形式接收当前的请求数据，但是这个和上⾯的接收⽅式仅能使⽤⼀个（⽤@RequestBody之后流就会关闭了）header@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) })String idstr = request.getHeader("id");if (StringUtils.isNumeric(idstr)) {id = Long.parseLong(idstr);}Form@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })@RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATIO常⽤ swagger 注解常⽤到的注解有：ApiApiModelApiModelPropertyApiOperationApiParamApiResponseApiResponsesResponseHeader1. api标记Api ⽤在类上，说明该类的作⽤。

swagger 使用手册Swagger 是一种用于构建、文档化和调试基于 RESTful 的 Web 服务的开源工具。

它提供了一组功能强大的工具和库，使开发人员能够以简单而有序的方式设计和测试 API，并生成规范化的文档。

本手册将指导您如何使用 Swagger 构建和文档化 API，并探索其各种功能和用法。

一、Swagger 简介Swagger 是一个开源工具，用于为 RESTful 的 Web 服务提供文档和调试功能。

它由一组用于定义、构建和文档化 API 的规范组成，包括Swagger 规范、Swagger UI 和 Swagger Codegen。

1. Swagger 规范：Swagger 规范是一种用于描述和定义 RESTful 接口的语言。

它使用YAML 或 JSON 格式，提供了一组结构化的字段，用于描述 API 的路径、操作、输入参数、输出响应等。

Swagger 规范允许开发人员以简洁而一致的方式定义和组织 API。

2. Swagger UI：Swagger UI 是一个用于可视化和交互式文档的工具。

它可以根据Swagger 规范生成漂亮且易于浏览的 API 文档，并提供了一组交互式功能，如请求构建器和响应查看器。

Swagger UI 可以帮助开发人员更好地了解和测试 API。

3. Swagger Codegen：Swagger Codegen 是一个代码生成工具，可以根据 Swagger 规范自动生成客户端和服务器端代码。

通过使用 Swagger Codegen，开发人员可以快速生成与API 规范一致的代码，从而加快开发速度并减少错误。

二、Swagger 的使用步骤下面是使用 Swagger 构建和文档化 API 的基本步骤：1. 定义 Swagger 规范：首先，您需要根据 API 的路径、操作、输入参数和输出响应等信息，以 Swagger 规范的格式编写 API 的定义。

您可以使用 YAML 或 JSON格式编写 Swagger 规范，然后将其保存为一个文件（如 swagger.yaml或 swagger.json）。

.netcore2.1使⽤swagger显⽰接⼝说明⽂档 项⽬之前开发完接⼝后，我们还需要写接⼝说明⽂档，现在有了swagger⽅便了很多，可以⽹页版直接测试，当然了也减少了我们的⼯作量。

使⽤swagger⽣成接⼝说明⽂档，⼤致需要2个步骤 1、从“管理 NuGet 程序包”对话框中：右键单击“解决⽅案资源管理器” > “管理 NuGet 包”中的项⽬将“包源”设置为“”在搜索框中输⼊“Swashbuckle.AspNetCore”从“浏览”选项卡中选择“Swashbuckle.AspNetCore”包，然后单击“安装” 2、添加并配置 Swagger 中间件public void ConfigureServices(IServiceCollection services){services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });});}public void Configure(IApplicationBuilder app, IHostingEnvironment env){if (env.IsDevelopment()){eDeveloperExceptionPage();}else{eHsts();}//启⽤静态⽂件中间件eStaticFiles();// Enable middleware to serve generated Swagger as a JSON endpoint.eSwagger();// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),// specifying the Swagger JSON endpoint.eSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");});eHttpsRedirection();eMvc();}services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });var xmlPath = bine(AppContext.BaseDirectory, "OfficalProject.xml");c.IncludeXmlComments(xmlPath);});//启⽤静态⽂件中间件eStaticFiles();// Enable middleware to serve generated Swagger as a JSON endpoint.eSwagger(c => { c.RouteTemplate = "swagger/{documentName}/swagger.json"; });// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),// specifying the Swagger JSON endpoint.eSwaggerUI(c =>{// c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");c.SwaggerEndpoint("v1/swagger.json", "SwaggerTest");//c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");}); 上⾯红⾊字体的就是修改的部分，下⾯我们的⽂档就有注释啦 重要！ 重要！ 重要！ 我们如在实际使⽤中，如遇到接⼝⽂档不能正常显⽰问题，可以调⽤这个地址进⾏排错 实际应⽤中，某些接⼝我们想不在外⾯显⽰，只需在控制器上⾯加上 [ApiExplorerSettings(IgnoreApi =true)][ApiExplorerSettings(IgnoreApi =true)] //设置该控制器不在swagger⽂档中显⽰[Route("api/[controller]")][ApiController]public class ValuesController : ControllerBase{// GET api/values[HttpGet]public ActionResult<IEnumerable<string>> Get(){return new string[] { "value1", "value2" };}}。

swagger3 openapidefinition 注解下载温馨提示：该文档是我店铺精心编制而成，希望大家下载以后，能够帮助大家解决实际的问题。

文档下载后可定制随意修改，请根据实际需要进行相应的调整和使用，谢谢!并且，本店铺为大家提供各种各样类型的实用资料，如教育随笔、日记赏析、句子摘抄、古诗大全、经典美文、话题作文、工作总结、词语解析、文案摘录、其他资料等等，如想了解不同资料格式和写法，敬请关注!Download tips: This document is carefully compiled by the editor. I hope that after you download them, they can help you solve practical problems. The document can be customized and modified after downloading, please adjust and use it according to actual needs, thank you!In addition, our shop provides you with various types of practical materials, such as educational essays, diary appreciation, sentence excerpts, ancient poems, classic articles, topic composition, work summary, word parsing, copy excerpts, other materials and so on, want to know different data formats and writing methods, please pay attention!在现代软件开发中，API（Application Programming Interface）已经成为了不可或缺的一部分。

.netcore的Swagger接⼝⽂档使⽤教程（⼆）：NSwag 上⼀篇介绍了Swashbuckle ，地址： 讲的东西还挺多，怎奈微软还推荐了⼀个NSwag，那就继续写吧！ 但是和Swashbuckle⼀样，如果还是按照那样写，东西有点多了，所以这⾥就偷个懒吧，和Swashbuckle对照的去写，介绍⼀些常⽤的东西算了，所以建议看完上⼀篇再继续这⾥。

⼀、⼀般⽤法 创建⼀个.net core项⽬（这⾥采⽤的是.net core3.1），然后使⽤nuget安装NSwag.AspNetCore，建议安装最新版本。

同样的，假如有⼀个接⼝： ///<summary>///测试接⼝///</summary>[ApiController][Route("[controller]")]public class HomeController : ControllerBase{///<summary>/// Hello World///</summary>///<returns>输出Hello World</returns>[HttpGet]public string Get(){return"Hello World";}} 接⼝修改Startup，在ConfigureServices和Configure⽅法中添加服务和中间件 public void ConfigureServices(IServiceCollection services){services.AddOpenApiDocument(settings =>{settings.DocumentName = "v1";settings.Version = "v0.0.1";settings.Title = "测试接⼝项⽬";settings.Description = "接⼝⽂档说明";});...}public void Configure(IApplicationBuilder app, IWebHostEnvironment env){ ...eOpenApi();eSwaggerUi3();...} 点击Try it out可以直接调⽤接⼝。

Swagger2文档的使用Swagger是一款遵循Restful风格的接口文档开发神器，支持基于API自动生成接口文档，接口文档始终与API保持同步，不再需要手动编写接口文档，并且采用全注解的方式，开发简单，代码侵入性低，对服务端开发的程序员来说非常方便，可以节约大量写接口文档的时间。

除此之外，Swagger生成的文档还支持在线测试，参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

一、Springboot整合Swagger21.在pom.xml文件中添加Swagger的maven依赖：<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>2.编写Swagger自定义配置类：/***类说明:自定义swagger配置信息*/@Configurationpublic class SwaggerConfig{@Beanpublic Docket creatApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//选择哪些路径和api会生成document.select()//controller路径.apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.con troller"))//对所有api进行监控//.apis(RequestHandlerSelectors.any())//对所有路径进行监控.paths(PathSelectors.any()).build();}//接口文档的一些基本信息private ApiInfo apiInfo(){return new ApiInfoBuilder()//文档主标题.title("springboot+swagger整合")//文档描述.description("test接口文档")//API的版本.version("1.0.0").termsOfServiceUrl("###").license("LICENSE").licenseUrl("###").build();}}3.在controller类添加swagger的注解：@Api(value="/user",tags={"用户操作接口"})@RestController@RequestMapping("/user")public class UserController{/***在方法上面添加@ApiOperation注解，表明该方法需要被swagger自动生成文档**@param userId用户ID*@return User用户*/@ApiImplicitParam(paramType="path",dataType="int",name="userId",value="用户ID",required=true)@ApiOperation(value="在方法上面添加@ApiOperation注解，表明该方法需要被swagger自动生成文档",notes="在方法上面添加@ApiOperation注解，表明该方法需要被swagger自动生成文档",httpMethod="GET")@GetMapping(value="/getUserById/{userId}")public User getUserById(@PathVariable Integer userId){User user=new User();user.setUserId(userId);user.setName("李四");user.setAge(18);user.setSex("男");return user;}}4.启动类上增加允许swagger@SpringBootApplication@EnableSwagger2public class SpringbootSwaggerApplication{public static void main(String[]args){SpringApplication.run(SpringbootSwaggerApplication.class,args);}}5.高版本的springboot访问路径匹配不到需要增加以下配置spring.mvc.pathmatch.matching-strategy=ant_path_matcher6.访问路径格式：http://服务器ip:端口/项目名称//swagger-ui.html例子：http://ip:/8080/swagger/swagger-ui.html二、swagger常用注解说明：1、@Api的使用说明：修饰controller类，标识这个类是swagger的资源，属性说明：∙tags：类的说明，但是tags如果有多个值，会生成多个list ∙value：也是类的说明，可以使用tags替代∙@Api(value="用户controller",tags={""}) @RestController@RequestMapping("/user")public class UserController{}2、@ApiOperation的使用说明：修饰controller的方法，表示一个http请求的操作，属性说明：∙value：用于方法描述∙notes：用于提示内容∙tags：可以重新分组，视情况而用）3、@ApiParam的使用说明：修饰方法的参数，用于添加参数说明与是否必填等元数据，属性说明：∙name：参数名∙value：参数说明∙required：是否必填∙@ApiOperation(value="获取用户信息",tags={"获取用户信息"},notes="注意问题点")@GetMapping("/getUserInfo")public User getUserInfo(@ApiParam(name="id",value="用户id",required=true)Integer id,@ApiParam(name="username",value="用户名")String username){User user=new User();user.setUserId(id);user.setName(username);user.setAge(18);user.setSex("男");return user;}4、@ApiModel的使用说明：修饰对象类，表示对对象类进行说明，用于参数用实体类接收的场景，属性说明∙value：表示对象名，可省略∙description：描述，可省略5、@ApiModelProperty的使用说明：修饰对象类中的属性，对属性进行说明，属性说明：∙value：字段说明∙name：重写属性名字∙dataType：重写属性类型∙required：是否必填∙example：举例说明∙hidden：是否隐藏∙@ApiModel(description="用户模型")@Datapublic class User{/***用户ID*/@ApiModelProperty("用户ID")private Integer userId;/***用户名*/@ApiModelProperty(value="用户名",name="name",example="lisi")private String name;/***性别*/@ApiModelProperty("性别")private String sex;/***年龄*/@ApiModelProperty(value="年龄",name="age",required=true)private Integer age;@ApiModelProperty(value="id数组",hidden=true)private Integer[]ids;}6、@ApiIgnore的使用说明：修饰类、方法、参数等，表示不显示在swagger文档中，比较简单,这里不做举例7、@ApiImplicitParam的使用说明：用于方法，表示单独的请求参数8、@ApiImplicitParams的使用说明：用于方法，包含多个@ApiImplicitParam，属性说明：∙name：参数ming∙value：参数说明∙dataType：数据类型∙paramType：参数类型∙example：举例说明∙@ApiOperation("查询测试")@GetMapping("/select")@ApiImplicitParam(name="name",value="用户名",dataType="String",paramType="query")public void select(){}@ApiOperation("查询测试2")@GetMapping("/select2")@ApiImplicitParams({@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType="query",example="lisi"),@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType="query")})public void select2(){}9、@ApiResponses与@ApiResponse使用说明：这两个注解都表示对响应结果进行说明10、@RequestMapping注解的推荐配置：◆value、◆method、◆produces●@ApiOperation("信息软删除")@ApiResponses({@ApiResponse(code=200,message="操作成功"),@ApiResponse(code=500,message="服务器内部异常"),@ApiResponse(code=401,message="权限不足")})@ApiImplicitParams({@ApiImplicitParam(paramType="query",dataType="Long",name="id", value="信息id",required=true)})@RequestMapping(value="/remove.json",method=RequestMethod.GET,produces= MediaType.APPLICATION_JSON_UTF8_VALUE)public User remove(Long id){return null;}三，更友好的界面1.添加依赖<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency>2.增加配置类@Configurationpublic class WebMvcConfig implements WebMvcConfigurer{@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry){ WebMvcConfigurer.super.addResourceHandlers(registry);registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}3.访问路径http://ip:端口/doc.htmlswagger3文档的使用一、SpringBoot集成Swagger31.删除了对springfox-swagger2的依赖；2.删除所有@EnableSwagger2…注解；3.添加了springfox-boot-starter依赖项；4.移除了guava等第三方依赖；5.文档访问地址改为http://ip:port/project/swagger-ui/index.html。

【⼯具】Swagger2写接⼝注释⼀、遇到的问题作为⼀名coder，经常需要向别⼈提供接⼝，或者调⽤别⼈的接⼝。

于是就有了接⼝参数是什么意思，要怎么传参数，返回值是什么意思……有多少调⽤⽅，就会有多少⼈来询问这些参数。

如果是长时间之后，⾃⼰或许都不知道这些参数是什么意思。

于是维护接⼝⽂档便成了⼀项必不可少的⼯作，维护⽂档也有很多问题：如果⼿⼯写会很费劲接⼝变更后可能会忘了同步⽂档……⼆、Swagger配置Swagger（）可以快速帮助实现接⼝api的维护与简单测试。

a、引⼊maven依赖包<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.5.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.5.0</version></dependency>b、配置Swagger@Configuration@EnableSwagger2@Profile("dev")public class SwaggerConfig {public static final String SWAGGER_SCAN_BASE_PACKAGE = "api.doc.demo.controller";public static final String VERSION = "1.0.0";@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()/**api接⼝包扫描路径*/.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))/**可以根据url路径设置哪些请求加⼊⽂档，忽略哪些请求*/.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()/**设置⽂档的标题*/.title("Swagger2 接⼝⽂档⽰例")/**设置⽂档的描述*/.description("更多内容请关注：")/**设置⽂档的联系⽅式*/.contact(new Contact("create by XXX", "", "xxxx.@"))/**设置⽂档的License信息->1.3 License information*/.termsOfServiceUrl("").license("xxx").licenseUrl("")/**设置⽂档的版本信息-> 1.1 Version information*/.version(VERSION).build();}}c、常⽤注解@ApiOperation ： api说明@ApiOperation(value="获取⽤户列表", notes="获取所有⽤户列表",produces = "application/json")@RequestMapping(value="/getList", method= RequestMethod.GET)public List<UserModel> getUserList() {return getDemoList();}@ApiResponses ：默认Response的基础上增加新的Response说明@ApiImplicitParam ：描述接⼝参数@ApiImplicitParam(name = "userId",value = "⽤户ID",dataType = "int",paramType = "path")@ApiImplicitParams ：多个参数@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "⽤户ID",paramType = "path",dataType = "int"),@ApiImplicitParam(name = "userName",value = "⽤户名称",paramType = "form",dataType = "string") })@ApiModel : model属性@ApiModel(value = "user", description = "user对象")public class UserModel {@ApiModelProperty(value = "ID", dataType = "Integer", required = true)private Integer userId;@ApiModelProperty(value = "⽤⼾名", dataType = "String")private String userName;@ApiModelProperty(value = "性別", dataType = "Integer", allowableValues = "0,1,2")private Integer sex;}这样就可以通过访问 http://localhost:8080/swagger-ui.html 看到接⼝API调⽤说明。

swagger以及swaggerUI使⽤的步骤1.swagger，可以这么理解swagger是接⼝规范。

Rest Api 传递参数的除了get请求外，put post，需要传递json。

或者就是直接都通过传递json到后台这⾥主要介绍⼀下springboot后台整合swagger的使⽤步骤。

如果要查看swagger(OpenApi)的规范，可以参考git的官⽅⽂件规范。

springboot 整合swagger的简单基本使⽤。

第⼀步：在pom.xml⽂件中引⼊依赖:12 3 4 5 6 7 8 9 10<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version></dependency>第⼆步：添加swagger的配置类12 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19@Configuration@EnableSwagger2@ComponentScan(basePackages = { "com.xxx.controller"})//扫描的包路径public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("⽤户登录")//接⼝标题.description("⽤户登录接⼝")//接⼝描述.version("v1.0")//版本号.contact(new Contact("name", "url", "email"))//联系⼈信息.build();}}如果没有添加@ComponentScan(basePackages={})扫描的包路径。