一、引言

1、什么是Swagger？

????????Swagger是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。它使得部署管理和使用功能強大的API從未如此簡單。Swagger讓文件的方法、參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API始終保持同步。

2、常用注解有哪些？

在軟件開發(fā)中，常用注解（Annotation）主要用在Java中，并且用于對代碼進行標(biāo)記和說明。下面列舉了一些常見的Java注解：

1. 與模型相關(guān)的注解：

   • @ApiModel：用于模型類上，對模型類做注釋。
   • @ApiModelProperty：用于屬性上，對屬性做注釋。

2. 與接口相關(guān)的注解：

   • @Api：用于controller上，對controller進行注釋。
   • @ApiOperation：用于API方法上，對該API做注釋，說明API的作用。
   • @ApiImplicitParams：用來包含API的一組參數(shù)注解，可以簡單的理解為參數(shù)注解的集合聲明。
   • @ApiImplicitParam：用在@ApiImplicitParams注解中，也可以單獨使用，說明一個請求參數(shù)的各個方面。

3. 其他常用注解：

   • @JsonProperty：用于屬性上、set/get方法上，該屬性序列化后可重命名。
   • @JsonFormat：用于屬性或者方法上，可格式化日期屬性的值。
   • @Date注解：使用這個注解可以代替實體類屬性的get和set方法。
   • @Mapper注解：這個接口在編譯時會生成相應(yīng)的實現(xiàn)類。
   • @RequestMapping：指定訪問方式，如果訪問方式不匹配，則無法進行訪問。

二、SpringBoot整合Swagger

1、導(dǎo)入依賴

pom.xml

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.5</version>
        </dependency>

        <!-- 使用1.5.22-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

2、創(chuàng)建Swagger配置類

package com.wfzldr.swagger2;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

@Configuration//和spring boot一起加載
@EnableSwagger2
//@Profile({"dev", "test"}) // dev(開發(fā))、test(測試)、prod(生產(chǎn))
public class Swagger2Configuration extends WebMvcConfigurationSupport {

    /**
     * 創(chuàng)建該API的基本信息  http://項目實際地址/doc.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
//                項目名
                .title("SpringBoot集成Swagger2")
//                系統(tǒng)的介紹
                .description("測試系統(tǒng)")
//                公司的首頁等等
                .termsOfServiceUrl("https://www.baidu.com")
//                sawgger的版本
                .version("1.0.0")
                .build();
    }

    /**
     * 創(chuàng)建API應(yīng)用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
//                基于那個包生成文檔
                .apis(RequestHandlerSelectors.basePackage("com.wfzldr.swagger2.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

3、案例

@Api

@Api注解用在類上，說明該類的作用?？梢詷?biāo)記一個Controller類做為swagger文檔資源。

案例演示

@RestController
@RequestMapping("/book")
@Api(value = "書籍管理", tags = "書籍管理")//設(shè)置tags這個值、value的值會被覆蓋
public class BookController {

}

@ApiOperation

@ApiOperation注解用在方法上，說明方法的作用，每一個url資源的定義。

案例演示

    @GetMapping("/list")
    @ApiOperation(value = "查詢所有的書籍")
    public JsonResponseBody<List<Book>> list() {
        ...
        return JsonResponseBody.success(list);
    }

@ApiImplicitParam

@ApilmplicitParam 注解用來描述一個參數(shù)，可以配置參數(shù)的中文含義，也可以給參數(shù)設(shè)置默認(rèn)值，這樣在接口測試的時候可以避免手動輸入；

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 如果有多個參數(shù)，則需要使用多個 @ApilmplicitParam 注解來描述， 多個 @ApilmplicitParam 注解需要放在一個 @ApilmplicitParams 注解中；

案例演示

@GetMapping("/listAndName")
    @ApiOperation(value = "模糊查詢書籍")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "書本名稱", required = true, dataType = "String"),
            @ApiImplicitParam(name = "price", value = "書本價格", required = true, dataType = "Double"),
    })
    public JsonResponseBody<List<Book>> listAndName(@ApiParam(name = "name", value = "書名") String name, double price) {
       ...
        return JsonResponseBody.success(list);
    }

@ApiModel和@ApiModelProperty

@ApiModel注解描述一個Model的信息（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景，請求參數(shù)無法使用 @ApiImplicitParam注解進行描述的時候；

@ApiModelProperty注解描述一個model的屬性。

案例演示

@ApiOperation(value="修改書本信息",notes = "修改書本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
 ? ?return bookService.updateByPrimaryKey(book);
}

注意：在這里可以不使用@ApiImplicitParam標(biāo)注Swagger中的參數(shù)信息，因為在這里的輸入?yún)?shù)是實體對象，而在實體對象中已經(jīng)使用@ApiModel和@ApiModelProperty注解進行了標(biāo)識。

package com.wfzldr.swagger2.model;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;

/**
 * <p>
 * 書籍表
 * </p>
 *
 * @author wfzldr
 * @since 2023-12-19
 */
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("書籍信息")
public class Book implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 書籍id
     */
    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty("書籍編號")
    private Long id;

    /**
     * 書名
     */
    @TableField("bookname")
    @ApiModelProperty("書名")
    private String bookname;

    /**
     * 價格
     */
    @TableField("price")
    @ApiModelProperty("價格")
    private Float price;

    /**
     * 書籍類型
     */
    @TableField("booktype")
    @ApiModelProperty(value = "書籍類型")//hidden = true用來隱藏
    private String booktype;


}

@ApiParam

作用在方法的參數(shù)上，用來描述接口的參數(shù)信息(一個參設(shè)置一個)

@ApiParam必須與@RequestParam、@PathVariable和@RequestHeader一起使用。

案例演示

@ApiOperation(value="新增書本信息",notes="新增書本信息")
@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<>();
}

三、生產(chǎn)環(huán)境下屏蔽Swagger

1、修改Swagger配置類

添加以下：

2、修改application.yml

修改application.yml文件，配置項目系統(tǒng)的運行環(huán)境（dev/test/prod）

????

spring:
  #配置swagger2生產(chǎn)和測試環(huán)境不可用
  profiles:
    active: prod

3、打包

使用maven package打包測試

4、運行測試

打開CMD，跳轉(zhuǎn)到target目錄，輸入命令：java -jar .\xxx.jar --spring.profiles.active=prod?？梢灾苯哟蜷_jar包修改application.yml配置文件中spring.profiles.active屬性切換運行環(huán)境，具體請參考以下配置：

開發(fā)環(huán)境：dev； 生產(chǎn)環(huán)境：prod； 測試環(huán)境：test；

???????

文章來源地址http://www.zghlxwxcb.cn/news/detail-777453.html

到了這里，關(guān)于【Swagger】常用注解的使用、SpringBoot的整合及生產(chǎn)環(huán)境下屏蔽Swagger的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！