SpringBoot集成Swagger2构建在线API文档的代码详解

SpringBoot集成Swagger2构建在线API文档的代码详解

第一部分：代码集成

pom.xml

io.springfox

springfox-swagger-ui

2.4.0

io.springfox

springfox-swagger2

2.4.0

com.github.xiaoymin

swagger-bootstrap-ui

1.6

swagger2配置类

package com.liud.demo.config;

import io.swagger.annotations.ApiOperation;

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;

/**

* TODO

* swagger2配置类

* @author liud

* @version 1.0

*/

@Configuration

@EnableSwagger2

public class Swagger2 {

//配置swagger2核心配置

@Bean

public Docket createRestApi(){

return new Docket(DocumentationType.SWAGGER_2) //指定api类型位swagger2

.apiInfo(apiInfo()) //用于定义api文档汇总信息

.select()

//.apis(RequestHandlerSelectors.basePackage("com.liud.demo.controller")) //指定生成文档的controller

//.apis(RequestHandlerSelectors.any()) //为任何接口生成API文档

//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@Api注解的Controller生成API文档

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //为有@ApiOperation注解的方法生成API文档

.paths(PathSelectors.any())

.build();

}

//api基本信息

private ApiInfo apiInfo(){

return new ApiInfoBuilder()

.title("SpringBootDemo的项目接口API") //文档标题

"",

"")) //联系人

.description("SpringBootDemo的项目接口API")//详细信息

.version("1.0.0")//文档版本号

.termsOfServiceUrl("")//网站地址

.build();

}

}

Controller

package com.liud.demo.controller;

import com.liud.demo.service.HelloService;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.beans.factory.annotation.Value;

import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;

/**

* TODO

*

* @author liud

* @version 1.0

*/

@RestController

@Api(tags = {"hello操作接口"})

public class HelloController {

@ApiOperation(value = "根据用户名获取用户信息接口")

@RequestMapping(value = "/getuserinfo",method = RequestMethod.POST)

public String getUserInfo(HttpServletRequest request,

@ApiParam(name="username",value = "用户名",required = true) String username){

return "输入的姓名："+username+",这个用户的信息已经存在！";

}

}

第二部分 使用 ①原路径模式

在浏览器上输入url:

http://{ip}:{port}/swagger-ui.html#/

我的地址：http://127.0.0.1:8081/swagger-ui.html

②文档模式

在浏览器上输入url:

http://{ip}:{port}/doc.html

我的地址：http://127.0.0.1:8081/doc.html

第三部分 swagger2常用注解

常用注解：

@Api()用于类；

表示标识这个类是swagger的资源

tags–表示说明

value–也是说明，可以使用tags替代

但是tags如果有多个值，会生成多个list

效果：

@ApiOperation()用于方法；

表示一个http请求的操作

value用于方法描述

notes用于提示内容

tags可以重新分组（视情况而用）

@ApiParam()用于方法，参数，字段说明；

表示对参数的添加元数据（说明或是否必填等）

name–参数名

value–参数说明

required–是否必填

@ApiParam(name="username",value = "用户名",required = true) String username

效果：

@ApiModel()用于类

表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段

表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略

@ApiImplicitParMdPCPQmam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个@ApiImplicitParam

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。