<p><img alt="" height="198" src="https://i-blog.csdnimg.cn/blog_migrate/a9a2645ffff164a3c77cc77dd9d32797.png" width="214" /></p> 

前言：

      我们对于Mybatis-Plus的分享较多，都是接触的一些数据库相关的知识，今天给大家带来的是Swagger2

1.介绍：

Swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：

- 接口的文档在线自动生成；
- 功能测试；

2.特点：

在线 API 文档可视化：

Swagger2 可以很容易地与 Spring Boot 集成。通过添加相应的依赖和配置，Swagger2 可以自动扫描项目中的 API，并生成相应的文档。Spring Boot 的注解与 Swagger2 的注解可以很好地配合，使得整合变得非常简单。
 

3.常用注解

1. 导入pom依赖
讯享网

讯享网

2. 引入配置类

（这是用于）

 Swagger2Configuration.java

介绍：

2.2、数据回显格式

JsonResponseBody.java

讯享网

JsonResponseStatus.java

3. 初步的访问swagger网址

        启动项目，项目默认访问路径+/doc.html即可

4. 第三方工具引入接口 

放入这个地址：

localhost:8080/v2/api-docs

就会加载项目：

@Api

@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

案例演示

讯享网@RestController @Api(value = “书本管理”,tags = {“书本管理”}) //tags可以代替value属性 @RequestMapping(“/book”) public class BookController {   … }

@ApiOperation

@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。

案例演示

@ApiOperation(value = “查询所有书本信息”, notes = “查询返回所有书本信息集合”,            produces = “application/json”) @GetMapping(value=“/queryAll”) public JsonResponseBody<List<Book>> queryAll(){    try {        return bookService.queryAll();   } catch (Exception e) {        e.printStackTrace();        return new JsonResponseBody<>(500,e.getMessage());   } }

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

paramType

案例演示

讯享网@ApiOperation(value=“查询单个书本信息”,notes = “查询单个书本信息”) @ApiImplicitParam(value=“书本ID”,name=“bookid”,required = true,dataType = “String”,defaultValue = “8f46b5018a6811e9a9c528d24413c293” ) @GetMapping(“/querySingleBook”) public Book querySingleBook(String bookid){    JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);    return json.getData(); }

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示

@ApiOperation(value = “新增书本信息”, notes = “新增书本信息”           ,produces = “application/json”,consumes = “application/json”) @ApiImplicitParams({            @ApiImplicitParam(name=“bookname”,value=“书本名称”,required = true,dataType = “String”),            @ApiImplicitParam(name=“price”,value=“书本价格”,required = true,dataType = “Double”),            @ApiImplicitParam(name=“booktype”,value=“书本类型”,required = true,dataType = “String”) }) @PostMapping(“/addBook”) public JsonResponseBody<?> addBook(@RequestParam String bookname,                                   @RequestParam Double price,                                   @RequestParam String booktype){    return bookService.insert(Book.builder()       .bookid(UUID.randomUUID().toString().replace(“-”,“”))       .bookname(bookname)       .booktype(booktype)       .price(price)       .build()); }

@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；

@ApiModelProperty注解描述一个model的属性。

案例演示

Controller

讯享网@ApiOperation(value=“修改书本信息”,notes = “修改书本信息”) @PostMapping(“/editBook”) public JsonResponseBody<?> editBook(@RequestBody Book book){    return bookService.updateByPrimaryKey(book); }

注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data @Builder @AllArgsConstructor @NoArgsConstructor @ApiModel(value=“书本对象”) public class Book implements Serializable { ​    /     * 书本编号     */    @ApiModelProperty(value=“书本编号”)    private String bookid; ​    /     * 书本名称     */    @ApiModelProperty(value=“书本名称”)    private String bookname; ​    /     * 书本价格     */    @ApiModelProperty(value=“书本价格”)    private Double price; ​    /     * 书本类型     */    @ApiModelProperty(value=“书本类型”)    private String booktype; ​    private static final long serialVersionUID = 1L; }

讯享网

@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

必须与、和一起使用。

案例演示

@ApiOperation(value=“新增书本信息1”,notes=“新增书本信息1”) @PostMapping(“/addBooks”) public JsonResponseBody<?> addBooks(            @ApiParam(name=“bookName”,value=“bookName”,required = true) @RequestParam(“bookName”) String bookName,            @ApiParam(name=“price”,value=“price”,required = true) @RequestParam(“price”) float price,            @ApiParam(name=“bookType”,value=“bookType”,required = true) @RequestParam(“bookType”) String bookType){      System.out.println(“bookName=”+bookName+“,price=”+price+“,bookType=”+bookType);    return new JsonResponseBody<>(); }

打jar包

运行jar

为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。

讯享网@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    
    ...
​
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

修改application.yml文件，配置项目系统的运行环境（dev/test/prod）

spring:  #配置swagger2生产和测试环境不可用 profiles:   active: prod

打开CMD，跳转到target目录，输入命令：java -jar .xxx.jar –spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：

开发环境：dev； 生产环境：prod； 测试环境：test；

      运行命令： java -jar .yxbook-0.0.1-SNAPSHOT.jar –spring.profiles.active=环境