文章目錄

• • 1. 如何使用
  • • 1.1 引入依賴
    • 1.2 創(chuàng)建swagger2配置類
    • 1.3 在controller上編寫我們的接口信息
    • 1.4 訪問http://ip:port/swagger-ui.html卻404？
  • 2 結(jié)合swagger2markup生成離線文檔PDF/HTML格式

? ? ? ?Swagger會(huì)自動(dòng)根據(jù)我們的接口來生成一個(gè)html頁面，在這個(gè)頁面上我們可以看到所有接口信息，信息中包含了有哪些參數(shù)，每個(gè)參數(shù)代表什么意思，如果是一個(gè)帶body體的請(qǐng)求，還會(huì)自動(dòng)幫我們生成json格式的body。并且還可以像http請(qǐng)求工具那樣進(jìn)行接口請(qǐng)求.極大的方便了我們編寫接口文檔。
作用：

• 接口的文檔在線生成
• 接口功能測(cè)試，替代postman

1. 如何使用

1.1 引入依賴

注意版本，經(jīng)常會(huì)有些意想不到的問題。2.2.2也是比較常用的版本

<!--swagger的依賴start--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.4.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.4.0</version></dependency><!--swagger的依賴end-->

1.2 創(chuàng)建swagger2配置類

@Configuration @EnableSwagger2 public class Swagger2Config { //swagger2的配置文件，這里可以配置swagger2的一些基本的內(nèi)容，比如掃描的包等等@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()//為當(dāng)前包路徑.apis(RequestHandlerSelectors.basePackage("com.jun.cloud")).paths(PathSelectors.any()).build();}//構(gòu)建 api文檔的詳細(xì)信息函數(shù)private ApiInfo apiInfo() {return new ApiInfoBuilder()//頁面標(biāo)題.title("Spring Boot 測(cè)試使用 Swagger2 構(gòu)建RESTful API")//創(chuàng)建人.contact(new Contact("余生君", "https://blog.csdn.net/java_collect", ""))//版本號(hào).version("1.0")//描述.description("API 描述").build();} }

? ? ? ?本例采用指定掃描的包路徑來定義(apis)，Swagger會(huì)掃描該包下所有Controller定義的API，并產(chǎn)生文檔內(nèi)容（除了被@ApiIgnore指定的請(qǐng)求）

1.3 在controller上編寫我們的接口信息

@RestController @RequestMapping("/alarmDevice") @Api(tags = "設(shè)備") public class AlarmDeviceController {@Autowiredprivate IAlarmDeviceService alarmDeviceService;/*** 根據(jù)name查詢?cè)O(shè)備信息*/@GetMapping("/name/get")@ApiOperation(value = "根據(jù)name查詢?cè)O(shè)備信息", notes = "查詢數(shù)據(jù)庫中某個(gè)設(shè)備的信息")public BaseResponse<List<AlarmDevice>> getByName(@ApiParam(name = "name", value = "設(shè)備名稱", required = true) String name){List<AlarmDevice> alarmDeviceList = alarmDeviceService.getByName(name);return new BaseResponse<>("200",alarmDeviceList);}@GetMapping("/{id}")@ApiOperation(value = "根據(jù)id查詢?cè)O(shè)備信息", notes = "查詢數(shù)據(jù)庫中某個(gè)設(shè)備的信息")@ApiImplicitParam(name = "name", value = "設(shè)備唯一標(biāo)識(shí)", required = true, dataType = "string",paramType = "path")public BaseResponse<List<AlarmDevice>> get(@PathVariable String id){List<AlarmDevice> alarmDeviceList = alarmDeviceService.getById(id);return new BaseResponse<>("200",alarmDeviceList);}//@ApiIgnore//使用該注解忽略這個(gè)API/*** 如果方法參數(shù)過多，可使用ApiImplicitParams和ApiImplicitParam寫在方法上*/@GetMapping("/list")@ApiOperation(value = "分頁查詢?cè)O(shè)備列表", notes = "")@ApiImplicitParams({@ApiImplicitParam(name = "pageNo", value = "頁碼", required = true, dataType = "Long"),@ApiImplicitParam(name = "pageNum", value = "頁數(shù)", required = true, dataType = "Long")})public BaseResponse<List<AlarmDevice>> list(Integer pageNo, Integer pageNum){//List<AlarmDevice> alarmDeviceList = alarmDeviceService.getByName(name);return new BaseResponse<List<AlarmDevice>>("200",null);}} @ApiModel(value="user對(duì)象",description="用戶對(duì)象user") public class User{@ApiModelProperty(value="用戶名",name="username",example="xingguo")private String username;@ApiModelProperty(value="狀態(tài)",name="state",required=true)private Integer state;private String password;private String nickName;@ApiModelProperty(value="id數(shù)組",hidden=true)private String[] ids;

• @Api：修飾整個(gè)類，描述Controller的作用
• @ApiOperation：描述一個(gè)類的一個(gè)方法，或者說一個(gè)接口
• @ApiParam：單個(gè)參數(shù)描述
• @ApiModel：用對(duì)象來接收參數(shù)
• @ApiIgnore：使用該注解忽略這個(gè)API
• @ApiParamImplicitL：一個(gè)請(qǐng)求參數(shù)
• @ApiParamsImplicit 多個(gè)請(qǐng)求參數(shù)

更詳細(xì)的swagger的注解含義可以參考github官網(wǎng)和這篇博客

1.4 訪問http://ip:port/swagger-ui.html卻404？

很有可能是靜態(tài)資源映射的問題，可以嘗試添加：

@Configuration public class ServletContextConfig extends WebMvcConfigurationSupport {/*** 這個(gè)自定義的類繼承自WebMvcConfigurationSupport，spring boot有一個(gè)子類EnableWebMvcConfiguration，并且是自動(dòng)config的.* 我們知道，如果一個(gè)類用戶自己在容器中生成了bean，spring boot就不會(huì)幫你自動(dòng)config。* 所以，問題的原因是我們把spring boot自定義的那個(gè)bean覆蓋了*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");super.addResourceHandlers(registry);}}

2 結(jié)合swagger2markup生成離線文檔PDF/HTML格式

? ? ? ?最常用的就是swagger2markup，即利用swagger.json生成asciidoc文檔，然后轉(zhuǎn)為html，pdf格式的文檔。但是配置有些繁瑣，所以就想可不可以利用一個(gè)demo工程直接訪問現(xiàn)有項(xiàng)目的swagger接口來生成離線文檔，這樣就不會(huì)在當(dāng)前項(xiàng)目引入額外的代碼與配置。

? ? ? ?demo工程地址為https://github.com/spiritn/spring-swagger2markup-demo.git。只需要將Swagger2MarkupTest里的SWAGGER_URL修改為自己項(xiàng)目的swagger接口地址，如

private static final String SWAGGER_URL = "http://localhost:8085/v2/api-docs";

保證接口可以訪問，然后運(yùn)行mvn clean test,即可在target/asciidoc/html 或者target/asciidoc/pdf下生成離線文檔，效果很不錯(cuò)，中文也支持的很好，可以點(diǎn)擊dto對(duì)象跳轉(zhuǎn)到對(duì)應(yīng)的描述：

總結(jié)

以上是生活随笔為你收集整理的swagger2的使用和swagger2markup离线文档的生成（最简单的方式）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。