swagger学习篇 | 易学教程

在spring boot下建议使用：

http://localhost:8080/swagger-ui.html

<dependency>    <groupId>com.spring4all</groupId>    <artifactId>swagger-spring-boot-starter</artifactId>    <version>1.7.1.RELEASE</version></dependency

添加依赖

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

1、swagger配置类

@Configuration  @EnableSwagger2  public class SwaggerConfig {
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "top.zlcxy.boot.examples.web";    public static final String VERSION = "1.0.0";
    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接口包扫描路径                .paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档，忽略哪些请求                .build();    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()            .title("Swagger2 接口文档示例")//设置文档的标题            .description("更多内容请关注：http://www.zlcxy.top")//设置文档的描述             .version(VERSION)//设置文档的版本信息             .contact(new Contact("zlcxy", "http://www.zlcxy.top", ""))//设置文档的联系方式             .termsOfServiceUrl("www.zlcxy.top")//设置文档的License信息             .build();    }}

2、注解使用

//ApiOperation 对接口的描述@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")  @RequestMapping(value="/users", method= RequestMethod.GET)public List<User> getUserList() {  List<User> r = new ArrayList<User>(users.values());    return r;}

// ApiResponses 返回结果的描述//ApiImplicitParam 接口参数的描述@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",produces = "application/json")@ApiResponses(value = {@ApiResponse(code = 405,message = "Invalid input",response = Integer.class)}) @ApiImplicitParam(name = "id",value = "用户ID",dataType = "int",paramType = "path")  @RequestMapping(value="/users/{id}", method= RequestMethod.GET)public User getUser(@PathVariable Integer id) {    return users.get(id);}

// ApiImplicitParams 多个参数的描述，paramType 有五个可选值 ：path, query, body, header, form@ApiOperation(value="更新用户名称", notes="更新指定用户的名称")@RequestMapping(value="/users/{id}", method= RequestMethod.POST)@ApiImplicitParams({           @ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),           @ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")})public void updateUserName(@PathVariable Integer id,@RequestParam String userName){    User u = users.get(id);    u.setName(userName);}

//ApiParam 参数描述  或者使用ApiImplicitParams注解 @ApiOperation(value="创建用户-传递简单对象", notes="传递简单对象",produces = "application/json")@RequestMapping(value="/users-1", method= RequestMethod.POST) public Map postUser(@RequestParam  String userName,@ApiParam("地址") @RequestParam(required = false) String address) {     User user = new User();    user.setId(Math.round(10));    user.setName(userName);    user.setAddress(address);    users.put(user.getId(), user);    return ImmutableMap.of("user",user);}

//ModelAttribute  传递复杂对象描述@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO, url参数拼接",produces = "application/json")@RequestMapping(value="/users-2", method= RequestMethod.POST) public Map postUser2(@ModelAttribute User user) {      users.put(user.getId(),user);    return ImmutableMap.of("user",user);}

//ApiModel 实体对象的描述 //ApiModelProperty 实体对象属性的描述 @ApiModel(value = "User", description = "用户对象")public class User {    @ApiModelProperty(value = "ID")    private Integer id;    @ApiModelProperty(value = "姓名")    private String name;    @ApiModelProperty(value = "地址")    private String address;    @ApiModelProperty(value = "年龄",access = "hidden")    private int age;    @ApiModelProperty(value = "性别")    private int sex;    .......}

3、配置

application.properties中配置参数

#改变请求的根路径springfox.documentation.swagger.v2.host = api.zlcxy.top#配置获取api docs json数据的请求路径 ，默认为/v2/api-docsspringfox.documentation.swagger.v2.path = /api

4、springfox-staticdocs 生成静态文档

maven引入jar包

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-staticdocs</artifactId>    <version>2.2.2</version>    <scope>test</scope></dependency>

生成json文件

@WebAppConfiguration@RunWith(SpringJUnit4ClassRunner.class)@SpringBootTest(classes = DemoBootApplication.class)public class Swagger2MarkupTest {    @Autowired    private WebApplicationContext context;    private MockMvc mockMvc;    @Before    public void setUp() {        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();    }
    @Test    public void createSpringfoxSwaggerJson() throws Exception {        String outputDir = "src/docs/json";  //将api-docs的json数据写入文件        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")                .accept(MediaType.APPLICATION_JSON))                .andExpect(status().isOk())                .andReturn();
        MockHttpServletResponse response = mvcResult.getResponse();        String swaggerJson = response.getContentAsString();        Files.createDirectories(Paths.get(outputDir));        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {            writer.write(swaggerJson);        }    }}

配置Maven Plugin

swagger2markup-maven-plugin，该插件将json文件转为asciidocasciidoctor-maven-plugin, 该插件将asciidoc转为html/pdf#执行Maven命令 ： mvn swagger2markup:convertSwagger2markup process-resources

 <plugins>        <plugin>            <groupId>io.github.swagger2markup</groupId>            <artifactId>swagger2markup-maven-plugin</artifactId>            <version>${swagger2markup.plugin.version}</version>            <dependencies>                <dependency>                    <groupId>io.github.swagger2markup</groupId>                    <artifactId>swagger2markup-import-files-ext</artifactId>                    <version>${swagger2markup.extension.version}</version>                </dependency>                <dependency>                    <groupId>io.github.swagger2markup</groupId>                    <artifactId>swagger2markup</artifactId>                    <version>${swagger2markup.version}</version>                </dependency>            </dependencies>            <configuration>                <swaggerInput>${swagger.input}</swaggerInput>                <outputDir>${generated.asciidoc.directory}</outputDir>                <config>                    <!--设置输出文件的语言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>                    <!--设置目录的展现方式-->                    <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>                    <!--扩展Overview的内容，可以增加一些自定义的内容-->                    <!--<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>                    <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>                    <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>                    <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security</swagger2markup.extensions.dynamicSecurity.contentPath>-->                </config>            </configuration>            <executions>                <execution>                    <phase>generate-sources</phase>                    <goals>                        <goal>convertSwagger2markup</goal>                    </goals>                </execution>            </executions>        </plugin>        <plugin>            <groupId>org.asciidoctor</groupId>            <artifactId>asciidoctor-maven-plugin</artifactId>            <version>1.5.3</version>             <dependencies>                <dependency>                    <groupId>org.asciidoctor</groupId>                    <artifactId>asciidoctorj-pdf</artifactId>                    <version>1.5.0-alpha.11</version>                </dependency>                 <dependency>                    <groupId>org.jruby</groupId>                    <artifactId>jruby-complete</artifactId>                    <version>${jruby.version}</version>                </dependency>                <dependency>                    <groupId>org.asciidoctor</groupId>                    <artifactId>asciidoctorj</artifactId>                    <version>${asciidoctorj.version}</version>                </dependency>            </dependencies>             <configuration>                <!--默认指向 ${basedir}/src/main/asciidoc-->                <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>                <!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->                <!--<sourceDocumentName>index.adoc</sourceDocumentName>-->                <attributes>                    <doctype>book</doctype>                    <toc>left</toc>                    <toclevels>3</toclevels>                    <numbered></numbered>                    <hardbreaks></hardbreaks>                    <sectlinks></sectlinks>                    <sectanchors></sectanchors>                    <generated>${generated.asciidoc.directory}</generated>                </attributes>            </configuration>            <executions>                <execution>                    <id>output-html</id>                    <phase>generate-resources</phase>                    <goals>                        <goal>process-asciidoc</goal>                    </goals>                    <configuration>                        <backend>html5</backend>                        <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>                    </configuration>                </execution>                <!-- 生成PDF -->                <!--<execution>                    <id>output-pdf</id>                    <phase>generate-resources</phase>                    <goals>                        <goal>process-asciidoc</goal>                    </goals>                    <configuration>                        <backend>pdf</backend>                        <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>                    </configuration>                </execution>-->
            </executions>        </plugin>    </plugins>