SpringBoot 集成Swagger
1.maven 配置
<!--springfox-swagger需要的最小依賴 start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
2. SwaggerConfig
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
/**
如果項(xiàng)目配置tomcat訪問路徑，例如qdp-wain-web這樣，需要配置下面的pathProvider方法，
未配置訪問路徑，則忽略pathProvider方法和HOST配置
**/
@Value("${spring.swagger.host}")
private String Host;
@Bean
public Docket swaggerSpringMvcPlugin(ServletContext servletContext) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//生成文檔的api對(duì)象定義
.select()
.apis(RequestHandlerSelectors.basePackage("com.jimingqiang.study"))//掃描生成文檔的包路徑
//.paths(PathSelectors.ant("/*Api/*"))//生成文檔的類訪問路徑，就是controller類里@RequestMapping("orderApi")
.paths(PathSelectors.any())
.build();
//.host(Host);//配置swagger前綴
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("JMQ-WEB構(gòu)建restful接口api")//文檔標(biāo)題
.description("此API提供接口調(diào)用")//文檔說明
.version("2.0").build();//版本號(hào)
}
}
-
SwaggerConfig必須與啟動(dòng)類同級(jí)，否則后臺(tái)報(bào)錯(cuò)：
No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'1539054671(1).jpg
3. swagger-ui.html的映射
代碼如下：
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
- 如果不配置上述代碼，我們?cè)谠L問http://localhost:8080/swagger-ui.html時(shí)，會(huì)顯示如下
-
后臺(tái)錯(cuò)誤：
No mapping found for HTTP request with URI [/swagger-ui.html] in DispatcherServlet with name 'dispatcherServlet'
4.注解
@Api：
作用在類上，用來標(biāo)注該類具體實(shí)現(xiàn)內(nèi)容。表示標(biāo)識(shí)這個(gè)類是swagger的資源 。
參數(shù)：
- tags：可以使用tags()允許您為操作設(shè)置多個(gè)標(biāo)簽的屬性，而不是使用該屬性。
- description：可描述描述該類作用。
@RestController
@RequestMapping("/swaggerApi")
@Api(value = "SwaggerValue", tags={"SwaggerController"},description = "swagger應(yīng)用", produces = MediaType.APPLICATION_JSON_VALUE)
public class SwaggerController {
@ApiOperation
用于方法；表示一個(gè)http請(qǐng)求的操作
value用于方法描述
notes用于提示內(nèi)容
tags可以重新分組（視情況而用）
@RequestMapping(value="/test", method= RequestMethod.GET)
@ApiOperation(value="獲取swagger信息",httpMethod = "GET",notes="注意問題點(diǎn)",produces = MediaType.APPLICATION_JSON_VALUE)
public String swaggerTest(@ApiParam(name="id",value="用戶id",required=true) Long id){
return "swagger"+id;
}
@ApiParam
用于方法，參數(shù)，字段說明；表示對(duì)參數(shù)的添加元數(shù)據(jù)（說明或是否必填等）
name–參數(shù)名
value–參數(shù)說明
required–是否必填
public String swaggerTest(@ApiParam(name="id",value="用戶id",required=true) Long id){
return "swagger"+id;
}
@ApiModel()用于類 ；表示對(duì)類進(jìn)行說明，用于參數(shù)用實(shí)體類接收
value–表示對(duì)象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段； 表示對(duì)model屬性的說明或者數(shù)據(jù)操作更改
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隱藏
@RequestMapping(value="/apiModeltest", method= RequestMethod.GET)
@ApiOperation(value="獲取ApiModel信息",httpMethod = "GET",notes="ApiModel注意問題點(diǎn)",produces = MediaType.APPLICATION_JSON_VALUE)
public String swaggerTest1(@RequestBody @ApiParam(name="用戶對(duì)象",value="傳入json格式",required=true) User user ){
return user.toString();
}
@Data
@ApiModel(value="user對(duì)象",description="用戶對(duì)象user")
public class User implements Serializable {
@ApiModelProperty(value="用戶名",name="username",required = true,example="xingguo")
private String name;
@ApiModelProperty(value="用戶年齡",name="age",required = true,example="24")
private int age;
}
@ApiIgnore()用于類或者方法上，可以不被swagger顯示在頁面上
比較簡(jiǎn)單, 這里不做舉例
@ApiIgnore()用于類或者方法上，可以不被swagger顯示在頁面上
? 比較簡(jiǎn)單, 這里不做舉例
@ApiImplicitParam() 用于方法 表示單獨(dú)的請(qǐng)求參數(shù)
?
@ApiImplicitParams() 用于方法，包含多個(gè) @ApiImplicitParam
name–參數(shù)名
value–參數(shù)說明
dataType–參數(shù)的數(shù)據(jù)類型
example–舉例說明
required-參數(shù)是否必填
paramType–查詢參數(shù)類型,這里有幾種形式
注意：當(dāng)我發(fā)POST請(qǐng)求的時(shí)候，當(dāng)時(shí)接受的整個(gè)參數(shù)，不論我用body還是query，后臺(tái)都會(huì)報(bào)Body Missing錯(cuò)誤。這個(gè)參數(shù)和SpringMvc中的@RequestBody沖突，索性我就去掉了paramType，對(duì)接口測(cè)試并沒有影響。
@RequestMapping(value="/apiImplicitParamsTest", method= RequestMethod.GET)
@ApiOperation(value="獲取apiImplicitParams信息",httpMethod = "GET",notes="apiImplicitParams注意問題點(diǎn)",produces = MediaType.APPLICATION_JSON_VALUE)
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用戶名字", required = true, dataType = "string", paramType = "query"),
@ApiImplicitParam(name = "id", value = "用戶id", required = false, dataType = "long", paramType = "query")})
public String apiImplicitParamsTest(Long id,String name ){
return name;
}
? ApiImplicitParam 與 ApiParam 的區(qū)別
? ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments.
- 對(duì)Servlets或者非 JAX-RS的環(huán)境，只能使用 ApiImplicitParam。
- 在使用上，ApiImplicitParam比ApiParam具有更少的代碼侵入性，只要寫在方法上就可以了，但是需要提供具體的屬性才能配合swagger ui解析使用。
- ApiParam只需要較少的屬性，與swagger ui配合更好。
彩蛋
微服務(wù)學(xué)習(xí)二：springboot與swagger2的集成
swagger2的常用注解，傳遞參數(shù)的注意使用方法](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#api)
