1：认识Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用：
- 接口的文档在线自动生成。
- 功能测试。
Swagger是一组开源项目，其中主要要项目如下：
- Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
- Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
2：Maven
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.2.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.2.2</version></dependency><!-- 下面这个界面更好看，更好用--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.5</version></dependency>
3：创建Swagger2配置类
import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;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;@Configuration@EnableSwagger2 //swagger注解public class SwaggerConfig {@Beanpublic Docket webApiConfig(){return new Docket(DocumentationType.SWAGGER_2).groupName("webApi").apiInfo(webApiInfo())//指定扫描的包.select()//.paths(PathSelectors) //路径过滤.build();}private ApiInfo webApiInfo(){return new ApiInfoBuilder().title("网站-课程中心API文档").description("本文档描述了课程中心微服务接口定义").version("2.0").contact(new Contact("lvguorui","111","111")).build();}}
4：添加文档内容
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
5：具体配置
5.1 注解
- @Api()用于类；
表示标识这个类是swagger的资源 - @ApiOperation()用于方法；
表示一个http请求的操作 - @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等） - @ApiModel()用于类；
表示对类进行说明，用于参数用实体类接收 - @ApiModelProperty()用于方法，字段；
表示对model属性的说明或者数据操作更改 - @ApiIgnore()用于类，方法，方法参数；
表示这个方法或者类被忽略 - @ApiImplicitParam() 用于方法；
表示单独的请求参数 - @ApiImplicitParams() 用于方法；
包含多个 @ApiImplicitParam
5.2 实践
@Api() - 用于类；表示标识这个类是swagger的资源
- tags–表示说明
- value–也是说明，可以使用tags替代
- 但是tags如果有多个值，会生成多个list ```java @Api(value=”用户controller”,tags={“用户操作接口”}) @RestController public class UserController {
}
@ApiOperation() - 用于方法；表示一个http请求的操作- value用于方法描述- notes用于提示内容- tags可以重新分组（视情况而用）@ApiParam() - 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）- name–参数名- value–参数说明- required–是否必填```java@Api(value="UserController",tags={"用户接口"})@RestControllerpublic class UserController {@ApiOperation(value="获取用户信息",tags={"获取用户信息"},notes="注意")@GetMapping("/getUserInfo")public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {User user = userService.getUserInfo();return user;}}
@ApiModel() - 用于类 ；表示对类进行说明，用于参数用实体类接收
- value–表示对象名
- description–描述
@ApiModelProperty() - 用于方法，字段； 表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏 ```java @ApiModel(value=”user”,description=”用户对象”) @Data public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value=”用户名”,name=”username”,example=”xingguo”) private String username; @ApiModelProperty(value=”状态”,name=”state”,required=true) private Integer state; private String password; private String nickName; private Integer isDeleted;
@ApiModelProperty(value="ids",hidden=true)private String[] ids;private List<String> idList;
}
```java@ApiOperation("修改用户信息")@PostMapping("/updateUserInfo")public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="json格式",required=true) User user){int num = userService.updateUserInfo(user);return num;}
5.3 配置类
@ApiIgnore() - 用于类或者方法上，可以不被swagger显示在页面上。
@ApiImplicitParam() - 用于方法，表示单独的请求参数
@ApiImplicitParams() - 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明
@ApiOperation("查询测试")@GetMapping("select")//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")@ApiImplicitParams({@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})public void select(){}
import com.google.common.base.Predicates;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.service.Parameter;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;import java.util.List;/*** swagger-api 配置** @author wzm* @version 1.0.0* @date 2019/6/15**/@Configuration@EnableSwagger2@EnableSwaggerBootstrapUIpublic class Swagger2 {/*** http://localhost:8085/fabric-net/swagger-ui.html* http://localhost:8085/fabric-net/doc.html*/private static final String SWAGGER_SCAN_BUSINESS_PACKAGE = "com.thyc.fabric.controller.business";private static final String BUSINESS_VERSION = "1.0.0";private static final String SWAGGER_SCAN_FABRIC_PACKAGE = "com.thyc.fabric.controller.fabric";private static final String FABRIC_VERSION = "1.0.0";@Beanpublic Docket createBusinessApi() {List<Parameter> pars = new ArrayList<>();ParameterBuilder ticketPar1 = new ParameterBuilder();ticketPar1.name("Authorization").description("登录令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();pars.add(ticketPar1.build());return new Docket(DocumentationType.SWAGGER_2).globalOperationParameters(pars)//分组名不支持中文.groupName("business").apiInfo(apiBusinessInfo()).pathMapping("/").select()// 对所有api进行监控.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BUSINESS_PACKAGE))// 错误路径不监控.paths(Predicates.not(PathSelectors.regex("/error.*")))// 对根下所有路径进行监控.paths(PathSelectors.regex("/.*")).build();}private ApiInfo apiBusinessInfo() {Contact contact = new Contact("thyc","thyc.com","thyc@email");return new ApiInfoBuilder()//设置文档的标题.title("Business")//设置文档的描述->1.Overview.description("业务模块数据管理")//设置文档的版本信息-> 1.1 Version information.termsOfServiceUrl("http://localhost:8085/fabric-net").contact(contact).version(BUSINESS_VERSION).build();}//------------------------------------------------------------------------------------------------------------------@Beanpublic Docket createFabricApi() {List<Parameter> pars = new ArrayList<Parameter>();ParameterBuilder ticketPar1 = new ParameterBuilder();ticketPar1.name("Authorization").description("登录令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();pars.add(ticketPar1.build());return new Docket(DocumentationType.SWAGGER_2).globalOperationParameters(pars)//分组名不支持中文.groupName("fabric").apiInfo(apiFabricInfo()).pathMapping("/").select()// 对所有api进行监控.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_FABRIC_PACKAGE))// 错误路径不监控.paths(Predicates.not(PathSelectors.regex("/error.*")))// 对根下所有路径进行监控.paths(PathSelectors.regex("/.*")).build();}private ApiInfo apiFabricInfo() {Contact contact = new Contact("thyc","thyc.com","thyc@email");return new ApiInfoBuilder()//设置文档的标题.title("Fabric-Network")//设置文档的描述->1.Overview.description("超级账本网络信息管理")//设置文档的版本信息-> 1.1 Version information.termsOfServiceUrl("http://localhost:8085/fabric-net").contact(contact).version(FABRIC_VERSION).build();}}
6: 测试网址
http://localhost:8088/swagger-ui.html 原路径
http://localhost:8088/doc.html 新路径
若有收获，就点个赞吧
0 人点赞
