首先明白swagger是什么 https://swagger.io/
根据官网的介绍:
Swagger Inspector:测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。
执行简单的API测试
生成OpenAPI文档
探索新的API功能
我的理解Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案。根据我的使用,当然我只是最简单的使用,我感觉Swagger有以下几个优点:
Swagger可以整合到代码中,在开发时通过注解,编写注释,自动生成API文档。
将前端后台分开,不会有过分的依赖。
界面清晰,无论是editor的实时展示还是ui的展示都十分人性化,如果自己仅仅用markdown来编写,又要纠结该如何展现,十分痛苦。
下面直接使用springBoot +swagger2案例来进行展示
第一创建springBoot项目,可以网上进行模板创建http://start.spring.io/
下面是我的项目结构
第二下面是具体的
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>springBoot-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>springBoot-swagger</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!--界面jar包-->
<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>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
package com.example.domain;
public class Book {
private Long Id;
public Long getId() {
return Id;
}
public void setId(Long id) {
Id = id;
}
public Book(Long id) {
super();
Id = id;
}
}
package com.example.config;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* <p>Title: SwaggerConfig</p>
* <p>Description: Swagger2的配置管理类</p>
* <p>Company: </p>
* @author LYH
* @date 2019年2月22日 上午10:34:04
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
// TODO Auto-generated method stub
return new ApiInfoBuilder()
.title("Spring Boot 中使用Swagger2构建RESTful APIs")
.description("myapp")
.termsOfServiceUrl("http://www.baidu.com")
.version("1.0")
.build();
}
}
package com.example.controller;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.example.domain.Book;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
/**
* <p>Title: BookController</p>
* <p>Description: </p>
* <p>Company: </p>
* @author LYH
* @date 2019年2月22日 上午10:49:54
*/
@RestController
@Api(tags = "BookController", description = "BookController | 通过书来测试Swagger")
@RequestMapping(value = "/books")
public class BookController {
Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long,Book>());
@ApiOperation(value = "创建图书", notes="创建图书")
@ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
@RequestMapping(value = "", method = RequestMethod.POST)
public String postBook(@RequestBody Book book) {
books.put(book.getId(), book);
return "success";
}
@ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public Book getBook(@PathVariable Long id) {
return books.get(id);
}
}
package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
@SpringBootApplication
@ComponentScan(basePackages = {"com"})
public class SpringBootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootSwaggerApplication.class, args);
}
}
第三步启动springBoot项目,浏览器访问地址http://localhost:8080/swagger-ui.html#/
点击 Try it out!之后将执行
点击get方法将获取刚刚创建的Book
到此项目就完成了,简单的完成了我们的目标。