当前位置: 首页 > news >正文

内蒙古建设工程造价管理网站软文云

内蒙古建设工程造价管理网站,软文云,宣传页模板图,网站死链优质博文:IT-BLOG-CN 如今,REST和微服务已经有了很大的发展势头。但是,REST规范中并没有提供一种规范来编写我们的对外REST接口API文档。每个人都在用自己的方式记录api文档,因此没有一种标准规范能够让我们很容易的理解和使用该…

优质博文:IT-BLOG-CN

如今,REST和微服务已经有了很大的发展势头。但是,REST规范中并没有提供一种规范来编写我们的对外REST接口API文档。每个人都在用自己的方式记录api文档,因此没有一种标准规范能够让我们很容易的理解和使用该接口。我们需要一个共同的规范和统一的工具来解决文档的难易理解文档的混乱格式。Swagger(在谷歌、IBM、微软等公司的支持下)做了一个公共的文档风格来填补上述问题。在本博客中,我们将会学习怎么使用SwaggerSwagger2注解去生成REST API文档。

Swagger(现在是“开放 API计划”)是一种规范和框架,它使用一种人人都能理解的通用语言来描述REST API。还有其他一些可用的框架,比如RAML、求和等等,但是 Swagger是最受欢迎的。它提供了人类可读和机器可读的文档格式。它提供了JSONUI支持。JSON可以用作机器可读的格式,而 Swagger-UI是用于可视化的,通过浏览api文档,人们很容易理解它。

一、添加 Swagger2 的 maven依赖

打开项目中的 pom.xml文件,添加以下两个 swagger依赖。springfox-swagger2 、springfox-swagger-ui。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.6.1</version>
</dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.6.1</version>
</dependency>

实际上,Swagger的 API有两种类型,并在不同的工件中维护。今天我们将使用 springfox,因为这个版本可以很好地适应任何基于 spring的配置。我们还可以很容易地尝试其他配置,这应该提供相同的功能——配置中没有任何变化。

二、添加 Swagger2配置

使用 Java config的方式添加配置。为了帮助你理解这个配置,我在代码中写了相关的注释:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import com.google.common.base.Predicates;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter
{@Beanpublic Docket api() {// @formatter:off//将控制器注册到 swagger//还配置了Swagger 容器return new Docket(DocumentationType.SWAGGER_2).select().apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any())//扫描 controller所有包.apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot"))).paths(PathSelectors.any()).paths(PathSelectors.ant("/swagger2-demo")).build();// @formatter:on}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry){//为可视化文档启用swagger ui部件registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

通过 api()方法返回 Docket,调用以下方法:
【1】apiInfo()方法中可以添加 api文档的基本信息(具体类型查看文档);
【2】select()方法返回 ApiSelectorBuilder实例,用于过滤哪些 api需要显示;
【3】apis()方法中填写项目中 Controller类存放的路径;

最后 build()建立 Docket。

三、验证 Swagger2的 JSON格式文档

在application.yml中配置服务名为:swagger2-demo

server.contextPath=/swagger2-demo

maven构建并启动服务器。打开链接,会生成一个JSON格式的文档。这并不是那么容易理解,实际上Swagger已经提供该文档在其他第三方工具中使用,例如当今流行的 API管理工具,它提供了API网关、API缓存、API文档等功能。

四、验证 Swagger2 UI文档

打开链接 在浏览器中来查看Swagger UI文档;

五、Swagger2 注解的使用

默认生成的 API文档很好,但是它们缺乏详细的 API级别信息。Swagger提供了一些注释,可以将这些详细信息添加到 api中。如。@Api我们可以添加这个注解在 Controller上,去添加一个基本的 Controller说明。

@Api(value = "Swagger2DemoRestController", description = "REST APIs related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {//...
}

@ApiOperation and @ApiResponses我们添加这个注解到任何 Controller的 rest方法上来给方法添加基本的描述。例如:

@ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")
@ApiResponses(value = {@ApiResponse(code = 200, message = "Success|OK"),@ApiResponse(code = 401, message = "not authorized!"),@ApiResponse(code = 403, message = "forbidden!!!"),@ApiResponse(code = 404, message = "not found!!!") })@RequestMapping(value = "/getStudents")
public List<Student> getStudents() {return students;
}

在这里,我们可以向方法中添加标签,来在 swagger-ui中添加一些分组。@ApiModelProperty这个注解用来在数据模型对象中的属性上添加一些描述,会在 Swagger UI中展示模型的属性。例如:

@ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")
private String name;

Controller 和 Model 类添加了swagger2注解之后,代码清单:Swagger2DemoRestController.java

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.springbootswagger2.model.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;@Api(value = "Swagger2DemoRestController", description = "REST Apis related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {List<Student> students = new ArrayList<Student>();{students.add(new Student("Sajal", "IV", "India"));students.add(new Student("Lokesh", "V", "India"));students.add(new Student("Kajal", "III", "USA"));students.add(new Student("Sukesh", "VI", "USA"));}@ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")@ApiResponses(value = {@ApiResponse(code = 200, message = "Suceess|OK"),@ApiResponse(code = 401, message = "not authorized!"),@ApiResponse(code = 403, message = "forbidden!!!"),@ApiResponse(code = 404, message = "not found!!!") })@RequestMapping(value = "/getStudents")public List<Student> getStudents() {return students;}@ApiOperation(value = "Get specific Student in the System ", response = Student.class, tags = "getStudent")@RequestMapping(value = "/getStudent/{name}")public Student getStudent(@PathVariable(value = "name") String name) {return students.stream().filter(x -> x.getName().equalsIgnoreCase(name)).collect(Collectors.toList()).get(0);}@ApiOperation(value = "Get specific Student By Country in the System ", response = Student.class, tags = "getStudentByCountry")@RequestMapping(value = "/getStudentByCountry/{country}")public List<Student> getStudentByCountry(@PathVariable(value = "country") String country) {System.out.println("Searching Student in country : " + country);List<Student> studentsByCountry = students.stream().filter(x -> x.getCountry().equalsIgnoreCase(country)).collect(Collectors.toList());System.out.println(studentsByCountry);return studentsByCountry;}// @ApiOperation(value = "Get specific Student By Class in the System ",response = Student.class,tags="getStudentByClass")@RequestMapping(value = "/getStudentByClass/{cls}")public List<Student> getStudentByClass(@PathVariable(value = "cls") String cls) {return students.stream().filter(x -> x.getCls().equalsIgnoreCase(cls)).collect(Collectors.toList());}
}

Student.java 实体类

import io.swagger.annotations.ApiModelProperty;public class Student
{@ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")private String name;@ApiModelProperty(notes = "Class of the Student",name="cls",required=true,value="test class")private String cls;@ApiModelProperty(notes = "Country of the Student",name="country",required=true,value="test country")private String country;public Student(String name, String cls, String country) {super();this.name = name;this.cls = cls;this.country = country;}public String getName() {return name;}public String getCls() {return cls;}public String getCountry() {return country;}@Overridepublic String toString() {return "Student [name=" + name + ", cls=" + cls + ", country=" + country + "]";}
}

六、swagger-ui 展示

现在,当我们的 REST api得到适当的注释时,让我们看看最终的输出。打开http://localhost:8080/swagger2-demo/swagger-ui。在浏览器中查看 Swagger ui文档。

http://www.zgjyky.com/news/260.html

相关文章:

  • 河北远策网站建设seo的形式有哪些
  • 政府单位建设网站有什么要求百度网站流量统计
  • 建站优化易下拉系统seo优化报价
  • 中国交通建设网官方网站免费seo优化工具
  • 后台网站更新 网站没显示百度seo官网
  • 帝国做网站免费发帖的平台有哪些
  • 小企业网站建设在哪能看企业培训网
  • 做网站备案需要什么接app推广接单平台
  • css网站案例河南网站建设哪里好
  • 医美三方网站怎么做磁力屋 最好用
  • java做的网站怎么突破磁力
  • 外国人学做中国菜的网站seo网站优化报价
  • 松原建设局网站百度一下官网入口
  • 做什么网站流量大扬州整站seo
  • 扁平式网站排名优化方案
  • 汽车网站建设方案爱站网关键词挖掘工具站长工具
  • 电子商务公司网站设计故事式软文广告300字
  • 英文版网站怎么做郑州网站营销推广
  • 挂机宝可以做网站石家庄网站建设案例
  • 建设工程网站单位名单线上推广是做什么的
  • 自考网站建设与管理网文推广怎么做
  • 公司网站横幅是做的吗aso优化哪家好
  • 中秋网页设计素材网站百度seo关键词优化工具
  • 一个人做公司管理网站开平网站设计
  • 建立主题网站的顺序苏州市网站
  • 将自己做的网站发布到百家号seo
  • 龙之向导外贸专区衡水seo优化
  • 深圳平台网站开发中国疾控卫生应急服装
  • 网站建设合同需要交印花税谷歌商店下载官方正版
  • 什么软件做高级网站html制作网站