Ŀ¼

SwaggerĽ

?ܳԹдһӿںԼȥӿĵ޸Ľӿں޸Ľӿĵ֮϶ᷢһǾ޸ĵߴĵǹ˾ѽӿĵдӿҪúܽ?дĵͿ۹ʣĹп©ģswaggerһдӿڵʱԶɽӿĵĶֻҪѭĹ淶дһЩӿڵ˵ע⼴ɡ

ŵȱ

?ŵ㣺

ԶĵֻҪڽӿʹעбעɶӦĽӿĵ
ԶĵǶ̬ɵģ޸˽ӿڣĵҲԶӦ޸ģҲעĻͲᷢ޸˽ӿڣȴǸ½ӿĵ
֧ߵԣswaggerṩߵýӿڵĹܡ

?ȱ㣺

ܴʱܰ㴦е顣ֻṩһ򵥵ߵԣ洢ĲʹPostmanYAPIִ֧ûĹܡ
ҪѭһЩ淶淶ġ˵ܻ᷵һjsonݣݿһMapʽģôǴʱܱעMapʽķݵÿֶε˵һʵĻǿͨעֶμ˵Ҳ˵swaggerƼʹGETʽύݵʱʹBodyƼʹqueryheader·Ȼֻߵԡ
ûнӿĵ¹Ȼһӿڸ֮󣬿ܲľɰĽӿϢ㡰ܡ뿴ɰĽӿϢЩҶȸ·ʱܻľɰĽӿڡôʱֻɺȥûעˣԿԿǽӿĵµʱע;ɰģȻд°ġȻͨӿĵԱȡ
ȻJavaʵвģͣpo,dto,voȣģ͵ΪһЩһû¼ʱֻҪusername,passwordȨ޵ʱҪȨޱϢʹUserʵĻĵоͻԶ˶ϢҪģʵ࣬¼ʱһLoginFormҪû-Ȩ޵ϢʱʹUserࡣȻˣswagger֮ʹžͻôˡ

?ȱдеܻ࣬swaggerе󡣵ʵҪǹ淶⣬淶ʱֻĴ淶ԣͼʼˣǰʲôӿڵĲʹһ࣬swaggerҪֿĳֲĴ淶ԡ

?ע´ʾSpring BootԲοswagger-demo

swagger

?ȽswaggerҲϽôʹãġٽ⡣

1.

?ע⣬ǰѾspring bootweb

        <dependency>
            <groupId>io.springfox</groupId>
            springfox-swagger2
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            springfox-swagger-ui
            <version>2.9.2</version>
        </dependency>

2.Swagger:

ҪʹswaggerǱswaggerãҪһswagger࣬ΪSwaggerConfig.java

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;

@Configuration // 
@EnableSwagger2 //swagger
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 ̶ģswagger2
//                .groupName("ֲʽϵͳ") // öĵʱôҪgroupNameʶ
                .apiInfo(apiInfo()) // APIϢ
                .select() // select()һApiSelectorBuilderʵ,ƽӿڱswaggerĵ
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // ָɨĸµĽӿ
                .paths(PathSelectors.any())// ѡеAPI,ֻΪAPIĵ
                .build();
    }

    /**
     * ڶAPIϢеAPIܱ⡢汾
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXĿAPI") //  ԶAPI
                .description("XXĿSwaggerAPI") // API
                .termsOfServiceUrl("") // ڶ
                .version("1.0") // 汾
                .build(); //
    }
}

3.

ǵSpring BootĿĬ8080˿ڣ㲻һע޸ĺurlhttp://localhost:8080/swagger-ui.html ȻͿԿһµĽ棬ʱûýӿݣʾNo operations defined in spec!

?ǽζӿڣԼswagger UIеݡ

ӿ

ӿʱӦǷģҴ󲿷ֶһcontrollerеģûصĽӿӦöUserControllerУôͬҵʱӦö/ֲͬĽӿ顣ӿʹ@Api֡ 磺

@Api(tags = "ɫ") //  tagsԵ֡
@RestController
public class RoleController {
}

@Api(tags = "û") //  tagsԵ֡
@RestController
public class UserController {
}

?Ҳɻtags飬ͺһЩıǩһʹñǩࡣ ?Controller£ӿ飩ûнӿڣôswagger uiǲʾģеĻͻʾ

ӿ

ʹ@ApiעһController֮нӿڣôͻĬĵûԶ˵

@Api(tags = "û")
@RestController
public class UserController {
    // ע⣬swaggerҪʹ@RequestMapping
    // Ϊ@RequestMapping֧ʽswaggerΪӿ7ʽĽӿĵ
    @GetMapping("/info") 
    public String info(String id){
        return "aaa";
    }
}

ǿʹ@ApiOperationӿڣ磺

    @ApiOperation(value = "û",notes = "ûnotes")
    @GetMapping("/test")
    public String test(String id){
        return "test";
    }



valueԵǽӿڵļ
notesӿڵ
tagsԶⶨӿ飬ӿѾ@Api(tags = "û")ӿڻֵˡûУԶʹtagstags = "ɫ"ýɫҲӿĵ

ӿ

ʹ@ApiOperationӿڣʵȱٽӿ˵Ƿֳ ?עһ£GETʽswaggerƼʹbodyʽҲǲϣGETʽʱʹjsonform-dataȷʽݣʱʹ·url(?ȻPOSTMANֵ֧)ӿڴݵjsonform-dataʽģʹPOSTʽá

һʵࡣ

ʱҪʹ@ApiModelעʵ࣬ȻڽӿжΪʵ༴ɣ

@ApiModel
- 
  - valueʵ
  - descriptionʵ˵
@ApiModelPropertyֶε塣
- 
  - valueֶ˵
  - exampleʾExample ValueĬֵãֶΪstringʱ򣬴ʱʾĬֵΪ"".
  - nameµֶɵֶ
  - allowableValuesֵ÷Χ{1,2,3}ֻȡֵ[1,5]ȡ15ֵ(1,5)15ֵ15ʹinfinity-infinityֵ[1, infinity]СֵΪ1ֵ
  - requiredֶǷĬfalse,
  - hiddenֶΣĬfalseҪҪʹtrueΪֶĬ϶ʾû@ApiModelProperty

// ʹ@ApiModelע
@ApiModel(value="û¼",description="û¼")
public class LoginForm {
    // ʹApiModelPropertyעֶԡ
    @ApiModelProperty(value = "û",required = true,example = "root")
    private String username;
    @ApiModelProperty(value = "",required = true,example = "123456")
    private String password;

    // ˴ʡθֵʱҪgetter,setter,swaggerҲҪ
}

    @ApiOperation(value = "¼ӿ",notes = "¼ӿڵ˵")
    @PostMapping("/login")
    public LoginForm login(@RequestBody LoginForm loginForm){
        return loginForm;
    }

Ƿʵࡣ

˵һΣGETʽswaggerƼʹbodyʽݣȻSpring MVCԶװGETǲҪʹform-datajsonȷʽݲʹPostmanԽӿڣswagger߲ǲ֧ ڷʵʹ@ApiImplicitParams``@ApiImplicitParam @ApiImplicitParamsڷͷϣ@ApiImplicitParam``@ApiImplicitParams棬һ@ApiImplicitParamӦһ @ApiImplicitParam

name֣Ҳֶε,ӿڵӦӦҲɣԿ
value
requiredעǷ
paramTypepath,query,body,form,headerȷʽڶڷʵʱ򣬳õֻpath,query,headerbodyformǲõġbodyڶɢֻjsonĽӿform-data,x-www-form-urlencodedʱܲʹswaggerҳAPIԣں潲BootstrapUIswaggerǿеԣBootstrapUIswaggerָ֧form-data``x-www-form-urlencoded

ʾһURL

    // ʹURL query
    @ApiOperation(value = "¼ӿ2",notes = "¼ӿڵ˵2")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",//
                    value = "û",//
                    required = true,//Ƿ봫
                    //paramTypeͣpath,query,body,form,header
                    paramType = "query"
                    )
            ,
            @ApiImplicitParam(name = "password",//
                    value = "",//
                    required = true,//Ƿ봫
                    paramType = "query"
                    )
    })
    @PostMapping(value = "/login2")
    public LoginForm login2(String username,String password){
        System.out.println(username+":"+password);
        LoginForm loginForm = new LoginForm();
        loginForm.setUsername(username);
        loginForm.setPassword(password);
        return loginForm;
    }

ʾURL·

    // ʹ·
    @PostMapping("/login3/{id1}/{id2}")
    @ApiOperation(value = "¼ӿ3",notes = "¼ӿڵ˵3")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id1",//
                    value = "û",//
                    required = true,//Ƿ봫
                    //paramTypeͣpath,query,body,form,header
                    paramType = "path"
            )
            ,
            @ApiImplicitParam(name = "id2",//
                    value = "",//
                    required = true,//Ƿ봫
                    paramType = "path"
            )
    })
    public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
        return id1+":"+id2;
    }

ʾheader

    // headerݲ
    @PostMapping("/login4")
    @ApiOperation(value = "¼ӿ4",notes = "¼ӿڵ˵4")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",//
                    value = "û",//
                    required = true,//Ƿ봫
                    //paramTypeͣpath,query,body,form,header
                    paramType = "header"
            )
            ,
            @ApiImplicitParam(name = "password",//
                    value = "",//
                    required = true,//Ƿ봫
                    paramType = "header"
            )
    })
    public String login4( @RequestHeader String username,
                          @RequestHeader String password){
        return username+":"+password;
    }

ʾģļϴ

    // ļϴʱҪ@ApiParam÷@ApiImplicitParamһ@ApiParamڲ
    // ҲԲע⣬swaggerԶ˵
    @ApiOperation(value = "ϴļ",notes = "ϴļ")
    @PostMapping(value = "/upload")
    public String upload(@ApiParam(value = "ͼƬļ", required = true)MultipartFile uploadFile){
        String originalFilename = uploadFile.getOriginalFilename();

        return originalFilename;
    }

    // ļϴʱ**swaggerֻܲԵļϴ**
    @ApiOperation(value = "ϴļ",notes = "ϴļ")
    @PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data")
    public String upload2(@ApiParam(value = "ͼƬļ", required = true,allowMultiple = true)MultipartFile[] uploadFile){
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < uploadFile.length; i++) {
            System.out.println(uploadFile[i].getOriginalFilename());
            sb.append(uploadFile[i].getOriginalFilename());
            sb.append(",");
        }
        return sb.toString();
    }

    // ļв
    @ApiOperation(value = "ļв",notes = "ļв")
    @PostMapping(value = "/upload3")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",
                    value = "ͼƬ",
                    required = true
            )
    })
    public String upload3(@ApiParam(value = "ͼƬļ", required = true)MultipartFile uploadFile,
                          String name){
        String originalFilename = uploadFile.getOriginalFilename();

        return originalFilename+":"+name;
    }

ӿӦ

ӿӦǷ鿴ӿĵܹ֪ӿڷصݵ塣

Ӧʵࣺ

ǰڶӿʱᵽʹ@ApiModelע࣬ӿڷ࣬ôϵ˵ҲΪӦ˵

    // ر@ApiModelע
    @ApiOperation(value = "ʵӦ",notes = "ΪʵĽӿ")
    @PostMapping("/role1")
    public LoginForm role1(@RequestBody LoginForm loginForm){
        return loginForm;
    }

ӦǷʵࣺ

swagger޷ԷʵӦϸ˵ֻܱעӦϢͨ@ApiResponses``@ApiResponseʵֵġ @ApiResponses``@ApiResponse``@ApiModelһʹá

    // ͵,ʱֶעͣʵswaggerƼʹʵ
    @ApiOperation(value = "ʵ",notes = "ʵ")
    @ApiResponses({
            @ApiResponse(code=200,message = "óɹ"),
            @ApiResponse(code=401,message = "Ȩ" )
    }
    )
    @PostMapping("/role2")
    public String role2(){
        return " {\n" +
                " name:\"㶫\",\n" +
                "     citys:{\n" +
                "         city:[\"\",\"\",\"麣\"]\n" +
                "     }\n" +
                " }";
    }

Swagger UIǿ

ܻUIǺܺÿһЩṩһЩSwagger UIǿȽеswagger-bootstrap-ui``swagger-bootstrap-uiΪ

UIԱȣ

ʹ

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            springfox-swagger2
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            springfox-swagger-ui
            <version>2.9.2</version>
        </dependency>
        <!-- swagger-bootstrap-ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            swagger-bootstrap-ui
            <version>1.8.7</version>
        </dependency>

2.swaggerע@EnableSwaggerBootstrapUI:

@Configuration // 
@EnableSwagger2 //swagger
@EnableSwaggerBootstrapUI // SwaggerBootstrapUI
public class SwaggerConfig {
    // ʡ
}

3.APIhttp://localhost:8080/doc.htmlԤbootstarpSwagger UI档

ŵ

1.?ÿһ

2.˵ˣBootstrapUIswaggerָ֧form-data``x-www-form-urlencoded

3.ָ֧ƵAPIĵ͵ȫAPIĵ

Spring Securityע

Spring BootSpring SecuritySwaggerʱҪص·ͷе·עǷ¼·

.antMatchers("/swagger**/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/**").permitAll()
.antMatchers("/doc.html").permitAll() // bootstarpSwagger UI棬һ

tokenĴ

swaggerֻ֧˼򵥵ĵԣһЩӿڣǲԵʱҪtokenϢдheaderУĿǰûԶͷĵط ?һ ʹSwagger BootstrapUIôڡĵȫֲheader

?swaggerȫֲã

        //жȫֲ˵ͷ
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<Parameter>();
        parameterBuilder.name("authorization").description("")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        parameters.add(parameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 ̶ģswagger2
                .apiInfo(apiInfo()) // APIϢ
                .select() // select()һApiSelectorBuilderʵ,ƽӿڱswaggerĵ
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // ָɨĸµĽӿ
                .paths(PathSelectors.any())// ѡеAPI,ֻΪAPIĵ
                .build().globalOperationParameters(parameters);

?ʹ@ApiImplicitParamsעһͷ磺

    // ҪĲǱõҪ,Ȩtoken
    @PostMapping("/login6")
    @ApiOperation(value = "tokenĽӿ",notes = "tokenĽӿ")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "authorization",//
                    value = "Ȩtoken",//
                    required = true,//Ƿ봫
                    paramType = "header"
            )
            ,
            @ApiImplicitParam(name = "username",//
                    value = "û",//
                    required = true,//Ƿ봫
                    paramType = "query"
            )
    })
    public String login6(String username){
        return username;
    }

Swaggerİȫ

1.Ȩ޹ԸswaggerȨ޹Ҫswaggerҳû룬Щspring securityshiroˣﲻ

2.ǲʽпԷʣʽйرSwaggerԶãͲswaggerҳˡʹ@Profile({"dev","test"})עֻdevtestSwaggerԶá ȻSpring Bootļ޸ĵǰprofilespring.profiles.active=release֮󣬴ʱ޷http://localhost:8080/swagger-ui.html

ߣprogor Ϊԭתע

SpringBoot集成Swagger实现API文档自动生成